zilmate 1.0.0

package/src/doc/shift-lifecycle-and-disputes.md

@@ -0,0 +1,95 @@
+# Shift Lifecycle And Disputes
+
+This guide explains how shifts move through the platform and how support should handle attendance, cancellations, no-shows, disputes, and completion.
+
+## Shift Statuses
+
+Typical statuses:
+
+- Draft: venue started but has not posted.
+- Open: workers can apply.
+- Filled: venue accepted a worker.
+- In progress: worker clocked in.
+- Completed: work done and ready for completion/payment processing.
+- Cancelled: shift no longer happening.
+
+## Standby Shifts
+
+Standby shifts should not display as normal available paid shifts immediately. They should only become relevant when the primary worker does not show or the venue activates standby need.
+
+Escalate if:
+
+- Worker sees primary and standby shift at the same time.
+- Standby shift shows `0` pay and still allows normal application.
+
+## Applications
+
+Workers apply for shifts. Venues review applications, match score, trust details, ratings, role history, videos, and certifications.
+
+Support should check:
+
+- Application status: pending, accepted, declined, withdrawn.
+- Shift owner.
+- Worker identity verification status.
+- Worker role match.
+
+## Acceptance
+
+When a venue accepts a worker:
+
+- Worker should see accepted shift.
+- Worker and venue should be able to message.
+- Ghana workers should receive SMS if phone is valid.
+- Venue should see attendance/arrival state where available.
+
+## Clock In And Clock Out
+
+Clock-in can happen by:
+
+- Venue QR code.
+- Worker manual clock-in where allowed.
+
+Expected behavior:
+
+- Once clocked in, shift should show active.
+- Returning to the shift page should not ask for clock-in again.
+- Clock-out should close the active time entry.
+
+Escalate if duplicate time entries appear or status resets.
+
+## No-Shows
+
+Each worker no-show should reduce reliability by `-3`.
+
+Support should:
+
+- Confirm shift date/time.
+- Confirm venue marked no-show.
+- Check messages/arrival evidence.
+- Escalate disputes if worker contests.
+
+## Cancellations
+
+Worker cancellation can affect reliability and fees. Venue cancellation can trigger refund/worker compensation rules depending on timing.
+
+Escalate if:
+
+- Worker bypasses cancellation rules.
+- Venue is charged incorrectly.
+- Refund is stuck.
+- Worker says venue canceled but marked worker no-show.
+
+## Disputes
+
+Collect:
+
+- Shift ID or role/date/venue.
+- Worker and venue user IDs if available.
+- Timeline.
+- Messages.
+- Clock-in/out records.
+- Payment records.
+- Screenshots if user has them.
+
+Do not decide high-risk disputes without admin review.
+

package/src/doc/support-macros.md

@@ -0,0 +1,40 @@
+# Support Macros
+
+Use these as starting points. Personalize them with the user name, shift, country, or provider.
+
+## Worker Cannot See Shifts
+
+Hi {{name}}, I can help. ZiloShift shows workers shifts in their saved city and matching roles. Please check that your country, city, town, and roles are saved under Profile. If those are correct and you still cannot see same-city shifts, send us the role and city you expect to see and we will investigate.
+
+## Worker Verification Pending
+
+Hi {{name}}, your verification may still be syncing. Ghana workers must complete front card, back card, liveness, and name match checks. Non-Ghana workers complete Didit verification. If you completed everything and still see pending, send us the time you verified and the account email so we can review the verification record.
+
+## Ghana Card Name Mismatch
+
+Hi {{name}}, the name on your ZiloShift account must match the name on your Ghana Card. This protects workers and venues from identity misuse. If your account name was entered incorrectly, we need to escalate it for review instead of changing it directly.
+
+## Venue Billing Failed
+
+Hi {{name}}, billing setup did not complete. I’ll check the payment provider connection for your country and the exact error returned. Ghana venues use Hubtel checkout, so if the checkout page did not open or returned an upstream error, we may need engineering to review the gateway logs.
+
+## Venue Cannot See Applicants
+
+Hi {{name}}, I’ll check whether the shift is open, whether workers have applied, and whether the applicant matching finished loading. If the applicant page stays blank for more than a few seconds, we’ll treat it as a loading issue and escalate it.
+
+## Worker Accepted For Shift
+
+Hi {{name}}, congratulations on being accepted. Please open the shift details and Messages to coordinate with the venue. On the day of the shift, clock in using the venue QR code or the available clock-in button, then clock out when finished.
+
+## SMS Campaign Test Failed
+
+The test SMS reached the gateway but Hubtel rejected it. Please check the returned details for phone format, sender ID length, SMS account credit, recipient blacklist status, or credential issues.
+
+## Payment Delay
+
+Hi {{name}}, I can check the payment status. Payout depends on the shift being completed, the venue/payment provider confirming funds, and your payout details being valid. Please send the shift date, venue/company name, and the payout method you selected.
+
+## Dispute Received
+
+Hi {{name}}, thanks for explaining. We’ll review the shift timeline, messages, clock-in/out records, and payment status before making a decision. Please send any screenshots or details that show what happened.
+

package/src/doc/venue-support-playbook.md

@@ -0,0 +1,145 @@
+# Venue Support Playbook
+
+Use this guide when helping venues set up company profiles, connect billing, post shifts, review applicants, accept workers, monitor attendance, message workers, and manage payments.
+
+## Venue Journey
+
+1. Sign up as a venue.
+2. Complete venue setup: company name, country, city, town, company type, about/company description.
+3. Verify business where required.
+4. Connect billing/payment.
+5. Post shifts with role, date, time, rate, description, dress code, instructions, certifications.
+6. Review applicants and AI match information.
+7. Accept worker.
+8. Coordinate in Messages.
+9. Confirm clock-in/out and completion.
+10. Handle ratings, disputes, or future preferred workers.
+
+## Common Venue Issues
+
+### Venue Cannot Connect Billing
+
+Check country:
+
+- Ghana venues use Hubtel checkout/pre-auth.
+- African countries supported by Paystack should use Paystack.
+- India uses Razorpay.
+- Other countries generally use Stripe.
+
+For Ghana Hubtel errors, check:
+
+- Gateway server has real `SUPABASE_SERVICE_ROLE_KEY`, not anon.
+- `payments` table has required compatibility columns such as `worker_amount`.
+- Hubtel gateway URL/token are configured.
+- Hubtel account number and checkout credentials are configured.
+
+Explain:
+
+> Billing setup must complete before some payment-related actions can work. Ghana uses Hubtel, so the checkout page should open from the Account page.
+
+Escalate if:
+
+- Error says upstream 500.
+- Error mentions schema cache.
+- Error mentions service_role key.
+- Hubtel checkout opens but never returns connected.
+
+### Venue Cannot Post A Shift
+
+Check:
+
+- Venue setup completed.
+- Venue country/city/town saved.
+- Company about/description exists.
+- Required role selected.
+- Date/time/rate are valid.
+- Billing requirements are satisfied for that country.
+
+Escalate if:
+
+- UI accepts inputs but shift does not save.
+- Role list is missing categories.
+- Rate suggestion blocks posting.
+
+### Venue Cannot See Applicants
+
+Check:
+
+- Shift is open or has applications.
+- Applicants have applied.
+- Venue is the owner of the shift.
+- AI match may take a few seconds; loading state should show.
+
+Explain:
+
+> Applicant matching can take a moment because ZiloShift scores role fit, reliability, location, and profile trust signals.
+
+Escalate if:
+
+- Blank screen remains after 10 seconds.
+- AI matching repeats every time and causes delays.
+- Applicant list appears for wrong venue.
+
+### Venue Wants To See Worker Trust Signals
+
+Venues should see:
+
+- Worker rating and reliability.
+- Completed shift count.
+- Work history summary.
+- Role history.
+- Intro video, if uploaded.
+- Certification badges and expiry dates, if available.
+- Reference checks where supported.
+
+Escalate if:
+
+- Video does not play.
+- Certifications are uploaded but not shown.
+- Ratings from past roles do not appear.
+
+### Venue Accepted Worker But Cannot Track Attendance
+
+Check:
+
+- Worker accepted status.
+- Worker has clocked in.
+- Map/arrival view availability.
+- Messages thread exists.
+
+Explain:
+
+> After accepting a worker, the venue should be able to coordinate through Messages and see attendance status. If live travel tracking is enabled, it should appear from the shift/applicant view.
+
+Escalate if:
+
+- Worker says they clocked in but venue still sees only Hired.
+- QR clock-in does not generate or scan.
+- Map does not load.
+
+## Venue Account Updates
+
+Venues should be able to update:
+
+- Company about.
+- City/town.
+- Contact phone.
+- Billing/payout connection where applicable.
+- Team details if enterprise features are enabled.
+
+Support should encourage venues to fill in company descriptions because workers use that to understand what the company does and what is expected.
+
+## Venue Tone Guide
+
+Use operational language:
+
+> I’ll check the shift status, billing connection, and applicant list first. Those three usually explain why a venue cannot hire or view workers.
+
+Avoid vague language:
+
+> Maybe the worker did not apply.
+
+Better:
+
+> I can see whether applications exist and whether the applicant list is failing to load.
+

package/src/doc/verification-and-trust.md

@@ -0,0 +1,88 @@
+# Verification And Trust
+
+This guide explains how support should handle identity verification, Ghana Card checks, Didit verification, name matching, and trust signals.
+
+## Verification Routes By Country
+
+- Ghana workers: Ghana Card flow with card front, card back, liveness/selfie, and Hubtel verification.
+- Non-Ghana workers: Didit KYC flow.
+- Venues: business verification flow where required.
+
+## Ghana Worker Verification
+
+The Ghana flow should:
+
+1. Capture front of Ghana Card.
+2. Capture back of Ghana Card.
+3. Capture liveness selfie.
+4. Scan card data.
+5. Check profile name against card name before server verification.
+6. Send verified card fields to server-side Hubtel verification.
+7. Store verification result and return status to frontend.
+
+Credentials must stay server-side. Never expose Hubtel Basic Auth or account numbers to users.
+
+## Name Matching Rule
+
+The worker profile name must match the ID holder. This prevents a person from using another person’s Ghana Card.
+
+If names do not match:
+
+- Ask the worker to confirm their account legal name.
+- Do not manually change names after signup without controlled support review.
+- Escalate if the worker says their legal name was entered incorrectly.
+
+## Name Change Risk
+
+Workers should not freely change first or last name after signup because a bad actor could:
+
+1. Change account name to match a stolen card.
+2. Verify with stolen card.
+3. Change account name back.
+
+Support action:
+
+- Treat name changes as sensitive.
+- Require admin review and proof.
+- Keep an audit trail.
+
+## Didit Verification
+
+Non-Ghanaian users use Didit. Support should:
+
+- Confirm user country.
+- Confirm they clicked Verify Now.
+- Ask for the verification status shown.
+- Ask whether they returned to the app after completing Didit.
+
+Escalate if:
+
+- Didit success does not sync back.
+- Didit webhook failed.
+- User is stuck pending after completion.
+
+## Admin Verification Queue
+
+Admins may review:
+
+- Pending ID verifications.
+- Rejected verification reasons.
+- Uploaded card/selfie assets where allowed.
+- Ghana verification raw response summary.
+
+Admins should not approve identities based only on a user message.
+
+## Trust Signals For Venues
+
+Trust features venues may use:
+
+- Ratings from past roles.
+- Completed shift count.
+- Reliability score.
+- No-show history.
+- Certifications.
+- Intro video.
+- Reference checks.
+
+Support should explain these as confidence signals, not guarantees.
+

package/src/doc/worker-support-playbook.md

@@ -0,0 +1,160 @@
+# Worker Support Playbook
+
+Use this guide when helping workers sign up, verify identity, find shifts, apply, clock in/out, message venues, update profile details, or get paid.
+
+## Worker Journey
+
+1. Sign up as a worker.
+2. Complete worker setup: country, city, town, roles, experience, certifications, availability, phone.
+3. Verify identity.
+4. Add payout details.
+5. Browse eligible shifts in their city.
+6. Apply for shifts matching their roles and location.
+7. If accepted, coordinate with the venue in Messages.
+8. Clock in when the shift starts.
+9. Clock out when the shift ends.
+10. Wait for completion processing and payout.
+
+## Common Worker Issues
+
+### Worker Cannot See Shifts
+
+Check:
+
+- Worker country, city, and town are saved.
+- Shift is in the same city as the worker.
+- Worker has selected roles matching available shifts.
+- Shift status is open.
+- Shift is not standby-only unless needed.
+- Worker profile setup is completed.
+
+Explain:
+
+> ZiloShift shows workers shifts in their own city so they do not travel too far or apply for work they cannot realistically attend. Anyone in the same city should see shifts across towns in that city.
+
+Escalate if:
+
+- Same-city open shifts exist but do not show.
+- Role filters are wrong after profile updates.
+- The worker sees corrupted text or missing company names.
+
+### Worker Wants To Verify Identity
+
+Ghanaian workers use the Ghana Card verification flow. Other countries use Didit verification.
+
+Check:
+
+- Worker country is correct.
+- Ghanaian workers should see Verify Now and be routed to Ghana verification.
+- Non-Ghanaian workers should be routed through Didit.
+
+Do not:
+
+- Ask for full ID numbers over chat.
+- Upload documents for the user.
+- Mark identity verified manually without admin review.
+
+### Worker Is Ghanaian And Verification Fails
+
+Ask:
+
+- Did they scan the front and back of the Ghana Card?
+- Did the liveness camera show their face?
+- Does the name on the account match the name on the card?
+- Did they use a clear, well-lit card image?
+
+Explain:
+
+> Ghana verification checks the card data and compares it against the worker profile details. If the profile name does not match the card, verification may stop before sending details for Hubtel verification.
+
+Escalate if:
+
+- Camera is blank.
+- Front/back scan captures but verification never proceeds.
+- Hubtel returns a provider error.
+- User was verified but still sees pending.
+
+### Worker Cannot Clock In
+
+Check:
+
+- Worker has been accepted for the shift.
+- Shift date/time has started or is close enough to start.
+- QR code clock-in is available from venue, or worker manual clock-in is enabled.
+- There is no existing active time entry.
+
+Explain:
+
+> Once clocked in, the shift should move to Active and remain active even if the worker leaves and returns to the page.
+
+Escalate if:
+
+- Worker clocked in successfully but the page later asks them to clock in again.
+- Duplicate time entries exist.
+- Clock-in works for QR but not manual, or vice versa.
+
+### Worker Was Accepted But Did Not Receive SMS
+
+For Ghana workers, acceptance SMS should be sent through Hubtel.
+
+Check:
+
+- Worker country is GH.
+- Profile phone number is present and valid.
+- Phone can normalize to Ghana MSISDN format, for example `23324xxxxxxx`.
+- Shift acceptance event happened.
+
+Escalate if:
+
+- Phone is valid but no SMS log/campaign result exists.
+- Hubtel gateway returns 400, 401, 402, or 500.
+
+### Worker Payout Issues
+
+Check:
+
+- Country and payout provider:
+  - Ghana: Hubtel mobile money or bank.
+  - Nigeria/Kenya/South Africa: Paystack.
+  - India: Razorpay.
+  - Other markets: Stripe.
+- Worker completed the shift.
+- Shift was processed by completion function.
+- Worker payout details are saved.
+
+Do not promise exact payout timing unless the payment status is confirmed.
+
+Escalate if:
+
+- Payment captured but payout not created.
+- Payout provider rejected account details.
+- Worker was paid the wrong amount.
+- Any fraud or duplicate-account concern exists.
+
+## Worker Profile Support
+
+Workers can update:
+
+- Phone.
+- City/town.
+- Roles.
+- Experience.
+- Certifications and certificate uploads.
+- Availability.
+- Payout details.
+
+Workers should not be able to update legal first/last name after signup without controlled support review, because name changes can weaken identity checks.
+
+## Worker Tone Guide
+
+Use clear, supportive language:
+
+> I can help with that. First I’ll check your account country, city, and role settings, because those decide which shifts appear for you.
+
+Avoid:
+
+> It should work.
+
+Better:
+
+> If your city and roles are saved correctly, same-city shifts should appear. If they do not, I’ll escalate it as a visibility bug.