Handoff — Wateera & Wajhati

Last updated: 2026-09-25 · State: product-complete, payments integrated (Moyasar + Tamara BNPL), Wajhati two-sided hiring platform established with cryptographic bundle verification and SEO public directory.

Resuming work? Read this file, then AGENTS.md. This is a living document: update it at the end of any session that changes the state below.

1. Where everything is

Environment rule learned the hard way: node-linker layout, ports and URLs must agree. SAAS_PORT/MARKETING_PORT/DOCS_PORT (3100/3101/3102) drive the dev scripts and must match the NEXT_PUBLIC_* URLs in .env.local.

2. What the product is

1. وتيرة (Wateera): Daily-performance loop (plan, execute, score, coach agents).
2. وجهتي (Wajhati): An independent two-sided Saudi talent and hiring platform (agentjob.io):
   • Candidate side: Default-private verifiable vaults, provenance-backed facts, finite approved application batches with cryptographic SHA-256 bundle hashes (computeBundleHash, computeBatchManifestHash).
   • Employer side: Vacancy publication, consented candidate reviews, interview scheduling.
   • Public SEO Directory: /jobs targeting the Arabic search term "وظائف" with JSON-LD JobPosting schema.
   • Payments: Moyasar (Mada, Credit Card, Apple Pay) + Tamara BNPL (3/4/6 installments) via @repo/payments.

3. Decisions already made (do not re-litigate without new evidence)

4. Verified state (as of the last session)

pnpm format:check && pnpm lint && pnpm type-check && pnpm test   # gates
pnpm build                                                       # 4 apps
pnpm build:worker && pnpm --filter saas exec wrangler deploy --dry-run
cp .agents/skills/template-to-product/scripts/verify-product.mjs apps/saas/ && \
  DEMO_EMAIL=... DEMO_PASSWORD=... node apps/saas/verify-product.mjs   # browser pass

• lint: 0 errors · type-check: 25 tasks passing · tests: 13 suites / 247 tests passing (including 26 payments tests, 60 core tests, 57 api tests) · build: 4/4 apps.
• Payments: Moyasar and Tamara BNPL providers fully tested with unit tests covering checkout links, webhooks, and idempotent records.
• Wajhati platform: candidate vaults, finite application batch cryptographic hashing, truthful matching, discovery agent, employer portal, and SEO public jobs directory verified.
• Browser pass on routes: no console errors.
• MCP: an end-to-end stdio run listed seven tools and called get_today, add_tasks, get_usage, run_pattern; an invalid task returned readable text; a cross-workspace call returned 403 and an audit entry.

5. What is left, and who owns it

Blocking a paid launch

Not blocking, known and documented: no scheduled jobs (no reminders), no notification types beyond two, MCP server runs from the repo rather than a published package, no pricing validation.

6. Traps that already cost time (do not rediscover them)

1. Two working copies of one repo drift. It happened (development/tamp vs Glm/tamp), and a pushed commit arrived in one while a local fix waited in the other. Keep one copy, or one branch per copy.
2. The dev server and pnpm build share apps/*/.next. Building while dev runs wedges the dev server, and the next browser pass times out on login with no useful error. Stop dev first.
3. A reset database looks like a code bug. 401 User not found means re-seed (pnpm db:seed); the seed prints a new demo password each run.
4. A running dev server holds a stale Prisma client and stale workspace packages. After a schema change or a change in packages/*, restart it (and clear .next if it still misbehaves).
5. MISSING_MESSAGE is fatal to a page. Rewriting an i18n namespace silently drops keys other components still use (app.menu.* is the easy one to break).
6. Plan copy lives in shared.json only. A pricing.* block in marketing.json shadows it and ships two prices for one plan.
7. NFKD breaks Arabic filenames (أ → ا + a mark the "safe characters" filter then deletes). Use NFC and allow \p{M}.
8. A warm hue holds more chroma than a cool one. Copy the shape of the accent ramp, never the numbers, when retinting the brand. --accent-500 is #E75724 exactly; --accent-600 is the solid-button step that keeps white labels ≥ 4.5:1.
9. History rewrites need --force-with-lease. Done once to drop GitHub's first commit; the remote was otherwise untouched.
10. GitHub reports a private repo you cannot see as "not found". The account switched mid-session (alswat1222 ↔ diamondcloudai) and a push failed with the same message a deleted repo gives. Check gh auth status before concluding anything was deleted.
11. The disk was full (116 MB free) at one point, which silently blocks installs. Regenerable artifacts under ~/development were cleaned (38.3 GB) and 597 tracked files that were served build output (a Laravel public/admin/dist) were restored. Watch df -h; a node_modules tree per project plus a .next per app adds up.

7. Security notes

• No secrets are stored in this document or the repo. .env.local is gitignored; only .env.local.example with empty values is tracked.
• A demo API key for the demo-team workspace exists in the local database (prefix bea4ccdc). It points at localhost and is worthless elsewhere, but revoke it if in doubt: pnpm --filter @repo/scripts api-key -- --revoke <keyId> --workspace demo-team.
• BETTER_AUTH_SECRET must be unique per environment; rotating it signs everyone out.