spine-framework 0.3.144 → 0.4.0

package/.framework/src/contexts/AuthContext.tsx

@@ -1,3 +1,13 @@
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:module_header:module_header" type="module_header" identity="module_header" parent=""]
+// CIL[DOC-MACRO purpose="React authentication context module: state, session, and provider."]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the module entry point, dependencies, constants, interfaces, hooks, and provider component."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="AuthContext, AuthProvider, useAuth, and helper functions" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports dependencies and defines constants, interfaces, and the provider for authentication." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="framework-developers"]
+
 
 
 
@@ -8,65 +18,112 @@
 
 
 
-// CIL[BEGIN chunk_id="AuthContext_module_header_1783749485" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Auth module imports and constants"]
-// CIL[DOC-RESPONSIBILITY responsibility="Define React context types and storage constants"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-context" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="type definitions" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Sets up imports and storage constants for auth management" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-context. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/migrations/015_simplify_apps_table.sql, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/RolesPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React, { createContext, useContext, useEffect, useState, useRef, useCallback } from 'react'
 import { supabase } from '../lib/supabase'
 import { setAccountId, apiFetch, onUnauthorized } from '../lib/api'
 import { User } from '../types/auth'
-
+// CIL[DOC-VECTOR type="context" content="purpose='React authentication context module: state, session, and provider.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:storage_version:constant" type="constant" identity="storage_version" parent="module_header"]
+// CIL[DOC-MACRO purpose="Define the storage_version constant."]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the storage_version value used by the auth context."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="constant value" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declarative constant with no runtime logic." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const STORAGE_VERSION = 1
+// CIL[DOC-VECTOR type="context" content="purpose='Define the storage_version constant.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:storage_version:constant"]
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:storage_key:constant" type="constant" identity="storage_key" parent="module_header"]
+// CIL[DOC-MACRO purpose="Define the storage_key constant."]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the storage_key value used by the auth context."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="constant value" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declarative constant with no runtime logic." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const STORAGE_KEY = 'spine_user'
+// CIL[DOC-VECTOR type="context" content="purpose='Define the storage_key constant.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:storage_key:constant"]
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:storage_ttl_ms:constant" type="constant" identity="storage_ttl_ms" parent="module_header"]
+// CIL[DOC-MACRO purpose="Define the storage_ttl_ms constant."]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the storage_ttl_ms value used by the auth context."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="constant value" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declarative constant with no runtime logic." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const STORAGE_TTL_MS = 24 * 60 * 60 * 1000
-const SESSION_TIMEOUT_MS = 15000
-// CIL[END chunk_id="AuthContext_module_header_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_storeduserenvelope_1783749485" type="interface" identity="StoredUserEnvelope" parent="none"]
-// CIL[DOC-MACRO purpose="Define stored user envelope interface"]
-// CIL[DOC-RESPONSIBILITY responsibility="Type definition for localStorage user storage"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-types" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Envelope wrapper for user data with version and timestamp" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-VECTOR type="context" content="purpose='Define the storage_ttl_ms constant.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:storage_ttl_ms:constant"]
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:session_timeout_ms:constant" type="constant" identity="session_timeout_ms" parent="module_header"]
+// CIL[DOC-MACRO purpose="Define the session_timeout_ms constant."]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the session_timeout_ms value used by the auth context."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="constant value" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declarative constant with no runtime logic." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-types. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+const SESSION_TIMEOUT_MS = 15000
+// CIL[DOC-VECTOR type="context" content="purpose='Define the session_timeout_ms constant.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:session_timeout_ms:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:storeduserenvelope:interface" type="interface" identity="storeduserenvelope" parent="module_header"]
+// CIL[DOC-MACRO purpose="TypeScript interface/type definition for storeduserenvelope."]
+// CIL[DOC-RESPONSIBILITY responsibility="Describe the shape of storeduserenvelope data."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="storeduserenvelope interface shape" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface declaration for type checking and contracts." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface StoredUserEnvelope {
   version: number
   timestamp: number
   user: User
 }
-// CIL[END chunk_id="AuthContext_storeduserenvelope_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_readstoreduser_1783749485" type="function" identity="readStoredUser" parent="none"]
-// CIL[DOC-MACRO purpose="Read stored user from localStorage"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and validate cached user data"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-utility" related_files="[\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="User | null" errors="none" side_effects="localStorage read"]
-// CIL[DOC-MICRO logic_summary="Validates version and TTL before returning cached user" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-utility. Direct callers: 1. Direct calls: 0. Related files: \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='TypeScript interface/type definition for storeduserenvelope.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:storeduserenvelope:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:readStoredUser:function" type="function" identity="readStoredUser" parent="module_header"]
+// CIL[DOC-MACRO purpose="Deserialize and validate the cached user from localStorage."]
+// CIL[DOC-RESPONSIBILITY responsibility="Read the stored user envelope, validate version and TTL, and return the user."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="User | null" errors="returns null on parse, version mismatch, expiry, or storage read error" side_effects="reads from localStorage"]
+// CIL[DOC-MICRO logic_summary="Reads localStorage by STORAGE_KEY, parses the JSON envelope, checks version and TTL, then returns user or null." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function readStoredUser(): User | null {
   try {
     const raw = localStorage.getItem(STORAGE_KEY)
@@ -79,21 +136,22 @@ function readStoredUser(): User | null {
     return null
   }
 }
-// CIL[END chunk_id="AuthContext_readstoreduser_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_writestoreduser_1783749485" type="function" identity="writeStoredUser" parent="none"]
-// CIL[DOC-MACRO purpose="Write user to localStorage"]
-// CIL[DOC-RESPONSIBILITY responsibility="Cache user data with envelope wrapper"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-utility" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="localStorage write"]
-// CIL[DOC-MICRO logic_summary="Stores user in envelope or removes entry if null" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-utility. Direct callers: 1. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Deserialize and validate the cached user from localStorage.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:readStoredUser:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:writeStoredUser:function" type="function" identity="writeStoredUser" parent="module_header"]
+// CIL[DOC-MACRO purpose="Persist or clear the cached user envelope in localStorage."]
+// CIL[DOC-RESPONSIBILITY responsibility="Serialize the user to a versioned envelope or remove the stored key."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="user: User | null" outputs="none" errors="silently swallowed" side_effects="writes or removes localStorage key"]
+// CIL[DOC-MICRO logic_summary="Writes a versioned envelope with timestamp when user is truthy, otherwise removes the storage key." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function writeStoredUser(user: User | null) {
   try {
     if (user) {
@@ -109,21 +167,22 @@ function writeStoredUser(user: User | null) {
   } catch {
   }
 }
-// CIL[END chunk_id="AuthContext_writestoreduser_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_getsessionwithtimeout_1783749485" type="function" identity="getSessionWithTimeout" parent="none"]
-// CIL[DOC-MACRO purpose="Get Supabase session with timeout"]
-// CIL[DOC-RESPONSIBILITY responsibility="Prevent hanging on stale sessions"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-utility" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="session data" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Races session fetch against timeout to prevent hanging" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-utility. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, .framework/src/components/ui/table-primitives.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Persist or clear the cached user envelope in localStorage.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:writeStoredUser:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:getSessionWithTimeout:function" type="function" identity="getSessionWithTimeout" parent="module_header"]
+// CIL[DOC-MACRO purpose="Fetch the Supabase session with a timeout fallback."]
+// CIL[DOC-RESPONSIBILITY responsibility="Wrap supabase.auth.getSession in a Promise.race to avoid hanging on slow networks."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{ data: { session: any | null } }" errors="returns null session on timeout or error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Races the Supabase getSession promise against a SESSION_TIMEOUT_MS timeout." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 async function getSessionWithTimeout(): Promise<{ data: { session: any | null } }> {
   try {
     return await Promise.race([
@@ -136,85 +195,110 @@ async function getSessionWithTimeout(): Promise<{ data: { session: any | null }
     return { data: { session: null } }
   }
 }
-// CIL[END chunk_id="AuthContext_getsessionwithtimeout_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_authcontexttype_1783749485" type="interface" identity="AuthContextType" parent="none"]
-// CIL[DOC-MACRO purpose="Define auth context interface"]
-// CIL[DOC-RESPONSIBILITY responsibility="Type definition for auth context value"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-types" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Defines shape of auth context with user state and actions" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-types. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Fetch the Supabase session with a timeout fallback.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:getSessionWithTimeout:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:AuthContextType:interface" type="interface" identity="AuthContextType" parent="module_header"]
+// CIL[DOC-MACRO purpose="TypeScript interface/type definition for AuthContextType."]
+// CIL[DOC-RESPONSIBILITY responsibility="Describe the shape of AuthContextType data."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="AuthContextType interface shape" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface declaration for type checking and contracts." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface AuthContextType {
   user: User | null
   isLoading: boolean
-  login: (email: string, password: string) => Promise<User | null>
+  login: (email: string, password: string, captchaToken?: string) => Promise<User | null>
   logout: () => Promise<void>
   refreshUser: () => Promise<User | null>
 }
+// CIL[DOC-VECTOR type="context" content="purpose='TypeScript interface/type definition for AuthContextType.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:AuthContextType:interface"]
 
-const AuthContext = createContext<AuthContextType | undefined>(undefined)
-// CIL[END chunk_id="AuthContext_authcontexttype_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_useauth_1783749485" type="function" identity="useAuth" parent="none"]
-// CIL[DOC-MACRO purpose="Access auth context hook"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide auth context to components"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="AuthContextType" errors="throws if no provider" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Returns auth context with safety check" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+
+
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:authcontext:constant" type="constant" identity="authcontext" parent="module_header"]
+// CIL[DOC-MACRO purpose="Define the authcontext constant."]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the authcontext value used by the auth context."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="constant value" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declarative constant with no runtime logic." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+const AuthContext = createContext<AuthContextType | undefined>(undefined)
+// CIL[DOC-VECTOR type="context" content="purpose='Define the authcontext constant.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:authcontext:constant"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:useauth:function" type="function" identity="useauth" parent="module_header"]
+// CIL[DOC-MACRO purpose="Hook to consume the AuthContext value."]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the auth context or throw an error when used outside an AuthProvider."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AuthContextType" errors="throws Error('useAuth must be used within an AuthProvider')" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Calls useContext(AuthContext) and validates the result is defined." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function useAuth() {
   const context = useContext(AuthContext)
   if (context === undefined) {
     throw new Error('useAuth must be used within an AuthProvider')
   }
+
+
   return context
 }
-// CIL[END chunk_id="AuthContext_useauth_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_authproviderprops_1783749485" type="interface" identity="AuthProviderProps" parent="none"]
-// CIL[DOC-MACRO purpose="Define auth provider props interface"]
-// CIL[DOC-RESPONSIBILITY responsibility="Type definition for AuthProvider component"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-types" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Simple props interface with only children" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-types. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Hook to consume the AuthContext value.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:useauth:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:AuthProviderProps:interface" type="interface" identity="AuthProviderProps" parent="module_header"]
+// CIL[DOC-MACRO purpose="TypeScript interface/type definition for AuthProviderProps."]
+// CIL[DOC-RESPONSIBILITY responsibility="Describe the shape of AuthProviderProps data."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="n/a" outputs="AuthProviderProps interface shape" errors="n/a" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface declaration for type checking and contracts." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface AuthProviderProps {
   children: React.ReactNode
 }
-// CIL[END chunk_id="AuthContext_authproviderprops_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_fetchusercontext_1783749485" type="function" identity="fetchUserContext" parent="none"]
-// CIL[DOC-MACRO purpose="Fetch user context with retry"]
-// CIL[DOC-RESPONSIBILITY responsibility="Get server-side user data with resilience"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-utility" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="User | null" errors="none" side_effects="API calls"]
-// CIL[DOC-MICRO logic_summary="Retries on network errors with exponential backoff" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-utility. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='TypeScript interface/type definition for AuthProviderProps.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:AuthProviderProps:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:fetchUserContext:function" type="function" identity="fetchUserContext" parent="module_header"]
+// CIL[DOC-MACRO purpose="Fetch remote user context with retries and transient error handling."]
+// CIL[DOC-RESPONSIBILITY responsibility="Load user data from /api/auth, tolerate transient network failures, and handle auth errors."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="maxRetries: number (default 2)" outputs="User | null" errors="returns null for 401/403, client errors, or unrecoverable exceptions" side_effects="makes HTTP GET request to /api/auth"]
+// CIL[DOC-MICRO logic_summary="Retry loop with exponential backoff; 5xx continues, 401/403/null returns, TypeError retries." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 async function fetchUserContext(maxRetries = 2): Promise<User | null> {
   let lastError: unknown = null
 
@@ -250,21 +334,22 @@ async function fetchUserContext(maxRetries = 2): Promise<User | null> {
   }
   return null
 }
-// CIL[END chunk_id="AuthContext_fetchusercontext_1783749485"]
-// CIL[BEGIN chunk_id="AuthContext_authprovider_1783749485" type="function" identity="AuthProvider" parent="none"]
-// CIL[DOC-MACRO purpose="Manage authentication state and lifecycle"]
-// CIL[DOC-RESPONSIBILITY responsibility="Handle auth flow, storage sync, and session management"]
-// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-provider" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Provider component" errors="auth errors" side_effects="localStorage, API calls, Supabase auth"]
-// CIL[DOC-MICRO logic_summary="Complex auth provider with storage sync, race guards, and cross-tab support" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-provider. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Fetch remote user context with retries and transient error handling.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:fetchUserContext:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/contexts/AuthContext.tsx:authprovider:function" type="function" identity="authprovider" parent="module_header"]
+// CIL[DOC-MACRO purpose="Provide authentication state and actions to the React component tree."]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage user state, session lifecycle, login/logout/refresh, and storage synchronization."]
+// CIL[DOC-CONTEXT module="AuthContext" layer="context" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts,.framework/src/lib/supabase.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-CONTRACT inputs="children: React.ReactNode" outputs="AuthContext.Provider with value { user, isLoading, login, logout, refreshUser }" errors="login may propagate Supabase error; useAuth throws outside provider" side_effects="updates localStorage, Supabase auth session, account id, and window storage listener"]
+// CIL[DOC-MICRO logic_summary="Initializes from cache, fetches/refresh session on mount, exposes callbacks, and listens to auth/storage events." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function AuthProvider({ children }: AuthProviderProps) {
   const storedUser = readStoredUser()
   const [user, setUser] = useState<User | null>(storedUser)
@@ -290,11 +375,15 @@ export function AuthProvider({ children }: AuthProviderProps) {
     setAccountId(ctx.account_id)
   }, [setUserWithStorage])
 
-  const login = useCallback(async (email: string, password: string) => {
+  const login = useCallback(async (email: string, password: string, captchaToken?: string) => {
     isLoggingInRef.current = true
 
     try {
-      const { data, error } = await supabase.auth.signInWithPassword({ email, password })
+      const { data, error } = await supabase.auth.signInWithPassword({
+        email,
+        password,
+        options: captchaToken ? { captchaToken } : undefined,
+      })
 
       if (error) throw error
 
@@ -449,4 +538,10 @@ export function AuthProvider({ children }: AuthProviderProps) {
     </AuthContext.Provider>
   )
 }
-// CIL[END chunk_id="AuthContext_authprovider_1783749485"]
+// CIL[DOC-VECTOR type="context" content="purpose='Provide authentication state and actions to the React component tree.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/lib/api.ts,.framework/src/types/auth.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/contexts/AuthContext.tsx:authprovider:function"]