docs: add comprehensive code comments, update README and TASKS, create training and troubleshooting guides

- Add JSDoc comments to API routes and business logic functions
- Update README.md with Phase 2 status and deployment/production notes
- Enhance TASKS.md with estimated timelines and dependencies
- Create docs/STAFF_TRAINING.md for team onboarding
- Create docs/CLIENT_ONBOARDING.md for customer experience
- Create docs/OPERATIONAL_PROCEDURES.md for daily operations
- Create docs/TROUBLESHOOTING.md for common setup issues
- Fix TypeScript errors in hq/page.tsx

app/api/kiosk/authenticate/route.ts

@@ -2,6 +2,9 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 import { Kiosk } from '@/lib/db/types'
 
+/**
+ * @description Authenticates a kiosk using API key
+ */
 export async function POST(request: NextRequest) {
   try {
     const body = await request.json()

app/api/kiosk/bookings/[shortId]/confirm/route.ts

@@ -18,6 +18,9 @@ async function validateKiosk(request: NextRequest) {
   return kiosk
 }
 
+/**
+ * @description Confirms a pending booking by short ID for kiosk
+ */
 export async function POST(
   request: NextRequest,
   { params }: { params: { shortId: string } }

app/api/kiosk/bookings/route.ts

@@ -18,6 +18,9 @@ async function validateKiosk(request: NextRequest) {
   return kiosk
 }
 
+/**
+ * @description Retrieves pending/confirmed bookings for kiosk
+ */
 export async function GET(request: NextRequest) {
   try {
     const kiosk = await validateKiosk(request)
@@ -72,6 +75,9 @@ export async function GET(request: NextRequest) {
   }
 }
 
+/**
+ * @description Creates a new booking for kiosk
+ */
 export async function POST(request: NextRequest) {
   try {
     const kiosk = await validateKiosk(request)

app/api/kiosk/resources/available/route.ts

@@ -18,6 +18,9 @@ async function validateKiosk(request: NextRequest) {
   return kiosk
 }
 
+/**
+ * @description Retrieves available resources for kiosk, filtered by time and service
+ */
 export async function GET(request: NextRequest) {
   try {
     const kiosk = await validateKiosk(request)

app/api/kiosk/walkin/route.ts

@@ -1,6 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 
+/**
+ * Validates kiosk API key and returns kiosk info if valid
+ */
 async function validateKiosk(request: NextRequest) {
   const apiKey = request.headers.get('x-kiosk-api-key')
   
@@ -18,6 +21,9 @@ async function validateKiosk(request: NextRequest) {
   return kiosk
 }
 
+/**
+ * @description Creates a walk-in booking for kiosk
+ */
 export async function POST(request: NextRequest) {
   try {
     const kiosk = await validateKiosk(request)
@@ -45,6 +51,7 @@ export async function POST(request: NextRequest) {
       )
     }
 
+    // Validate service exists and is active
     const { data: service, error: serviceError } = await supabaseAdmin
       .from('services')
       .select('*')
@@ -75,6 +82,7 @@ export async function POST(request: NextRequest) {
 
     const assignedStaff = availableStaff[0]
 
+    // For walk-ins, booking starts immediately
     const startTime = new Date()
     const endTime = new Date(startTime)
     endTime.setMinutes(endTime.getMinutes() + service.duration_minutes)