Code@ Work Guide

1. TRACKING & PROJECT MANAGEMENT

Core Tool: Code@ Project Tracker

Location: ~/Desktop/codeat-hub/ | Live Dashboard: https://codeat-index.pages.dev/status

Commands

# List all projects and IDs
~/Desktop/codeat-hub/track.sh list

# View one project before changing
~/Desktop/codeat-hub/track.sh show <id>

# Update project status
~/Desktop/codeat-hub/track.sh set <id> pct=85 phase=building blocker="…" next="…" owner=you

# Add new project
~/Desktop/codeat-hub/track.sh add <id> name="ProjectName" cat=products phase=building pct=10 desc="…"

# Manage user todos (what only the user can do)
~/Desktop/codeat-hub/track.sh todo <id> ls
~/Desktop/codeat-hub/track.sh todo <id> add "Rotate the Neon password" kind=action urgent=1
~/Desktop/codeat-hub/track.sh todo <id> rm <n>

# Manage Claude's remaining work
~/Desktop/codeat-hub/track.sh ctodo <id> add "…"
~/Desktop/codeat-hub/track.sh ctodo <id> rm <n>

Field Definitions

• pct (0-100): Distance to a real user using it, NOT code written
• phase: shipped | building | blocked | paused
• blocker: One concrete thing standing in the way
• next: Single next action (not a list)
• owner: you (user action) | claude (our work) | none

Percentage Honesty Rules

1. The number reflects distance to a real user using it, not code written
2. Deployed but on mock data is not 95%. State gaps in blocker.
3. Never round up. Inflated rows cost wrong decisions.
4. Lowering is valid. Do it immediately when truth is worse.
5. Blocker should name one thing, concretely — "needs a Gemini key", not "needs config"

---

2. SAFETY & GUARDS

What Happened: OTP_CHANNEL="mock" in wrangler.toml [vars] deployed to production URLs → login codes issued for ANY phone.

The value that SHIPS must be the SAFE one. The unsafe value must live in a file that CANNOT ship.

Prevention Pattern

# ✓ SAFE: wrangler.toml [vars] — this is what ships
[vars]
ENVIRONMENT="production"
OTP_CHANNEL="sms"        # Real SMS, not mock
PAYMENT_RAIL="stripe"

# ✓ SAFE: .dev.vars (gitignored, cannot ship)
ENVIRONMENT="development"
OTP_CHANNEL="mock"       # Mock OK locally
PAYMENT_RAIL="dev"       # Fake stripe key locally

Pre-Deploy Safety Checklist

1. Grep shipped config for dev/mock keywords
2. Test the DEFAULTS, not happy path
3. Curl production before marking shipped

Check the RESOLVED HOST (actual connection), never the named file. Fail closed if you can't verify.

The Shape: Defensive code turns errors into plausible wrong answers. Test suites match author's imagination, not reality.

---

3. HOOKS SETUP

When to Add: Before real build work starts on ANY project. At minimum one hook, tailored to what breaks there.

Hook Type 1: TypeCheck (PostToolUse on Edit|Write)

When: TS/build projects with strict type safety required

Configuration

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/typecheck.sh"
          }
        ]
      }
    ]
  }
}

Hook Type 2: Production DB Guard (PreToolUse on Bash)

Never trust a filename saying "staging" — resolve the actual host.

Hook Type 3: Mock OTP Deploy Guard (PreToolUse on Bash)

Blocks deploy if OTP not yet implemented.

Hook Type 4: Secret Scan Guard (PreToolUse on Edit|Write)

Scans for API keys, JWT, PEM blocks, embedded DB passwords.

Hook Type 5: Destructive Git Guard (PreToolUse on Bash)

Blocks repo-wide discards in concurrent work.

---

4. DEPLOYMENT PATTERNS

Stack: Cloudflare Pages + Workers + D1

• Frontend: Vite SPA (React 19 + Tailwind 4)
• Backend: Cloudflare Pages Functions (Workers runtime)
• Database: Cloudflare D1 (SQLite)
• Secrets: wrangler pages secret put

Deploy Command

npm run deploy

#	Trap	Silent Failure	Fix
1	wrangler d1 execute --local while dev running	Stale connection; writes vanish	Stop dev → reseed → restart
2	--d1 DB=<name> to pages dev	Separate empty DB; ignores seeded one	Remove the flag
3	_redirects with SPA rule	Unnecessary; Pages already serves SPA shell	Delete the rule
4	CF 1010 to non-browser UAs	Python requests blocked by Cloudflare	Send browser UA from scripts
5	CSS @import after @tailwind	Dropped by spec; no error, custom props undefined	Import from main.tsx; let Vite bundle
6	R2 commands without --remote	Defaults to LOCAL; bucket untouched	Always pass --remote
7	Framework build generates wrangler config	Wrangler reads generated file, not your edit	Deploy via npm run deploy
8	Pages secret race (set, then deploy)	Deploy gets old binding value; 403 on new secret	Set → wait 15s → deploy → wait 15s

Noor (JAT ERP): Direct-to-Production Deploy

Repository: ~/Desktop/Noor | Live: jat-erp.com

Deploy finished work DIRECTLY to production. No staging step.

Pre-Deploy Gates (in order)

npx tsc --noEmit              # Type check
npx eslint .                  # Linter
npm run test -- --run         # Unit tests (expect 344 passing)
node scripts/check-selectors.mjs  # Selector check (expect 21/21)
npm run deploy                # Deploy to jat-erp.com

---

5. TESTING PATTERNS

Pattern: Code & Schema Order

Code and schema must ship in the right order. Migrate THEN deploy.

Process: Mutating Scripts Must Announce Target

Rule: Before running ANY mutating script, read how it resolves its target.

Scripts Known to be SELF-GUARDED

- apply-sql.mjs
- migrate-tenants.mjs
- wipe-transactional.mjs
- restore.mjs
- seed-coa.mjs

Scripts Known to be DANGEROUS

- npm run seed
- npm run db:push / db:migrate
- scripts/seed-codat-templates.mjs
- Any raw psql / TRUNCATE / DELETE / DROP

---

6. ARCHITECTURE PATTERNS

Directory Structure: Desktop vs Desktop Folders

Location	Purpose	Example
~/Desktop/	Active projects (deployed, building, under active dev)	Noor, Elite×3, Laqta, Wain, Classico
~/Desktop Folders/ (DF)	Reference, templates, learning PDFs, old versions	Learning PDFs, French reactivation, Ideas

Pattern: Core 2.0 Dashboard

Tokens + primitives, NOT composition templates. Re-COLOR, not RE-BUILD.

Key Finding (2026-07-10): Both ERPs (X-Grid + Noor) are ALREADY Core 2.0. Do NOT re-skin them — re-brand in place only.

Pattern: Design System Default

Default: Material Design (M3), light mode only, unless user explicitly overrides

---

7. SKILL SETUP & MCP AUTH

Skill Installation Path

Location: ~/.claude/skills/<skill-name>/

Skills in Active Use

• /core-2.0-dashboard — dashboard/ERP/admin UI build/re-skin
• /erp-builder — reproduce Noor per client as standalone clone
• /ds-material3 — Material Design 3 setup for any project
• /dataviz — chart/graph/dashboard color/accessibility

Figma MCP Hard Prerequisites

ALL FOUR required:

1. Figma desktop app running (browser doesn't work)
2. Dev Mode enabled in desktop toolbar
3. Paid seat (Dev or Full tier, not free)
4. Runs locally on your machine (local SSE endpoint)

---

8. INFRASTRUCTURE & CREDENTIALS

Neon Database (Production & Staging)

Serverless Postgres
- Branches for staging (cheap, destroys on reset)
- Always use pooled connection (?sslmode=require)
- Run migrations against staging first, then production

Supabase (Auth, Real-time, Storage)

- API key (anon) in public config
- JWT secret in .dev.vars only
- Client: Supabase Auth (browser handles login)
- Server: Verify token from Authorization header

Cloudflare R2 (File Storage)

wrangler r2 bucket list                              # List buckets
wrangler r2 object put my-bucket/file.jpg ./file --remote  # Upload (ALWAYS --remote)
wrangler r2 object get my-bucket/file.jpg --remote         # Download
wrangler r2 object delete my-bucket/file.jpg --remote      # Delete

Key Rule

wrangler r2 object commands default to LOCAL storage. Always pass --remote.

Who Creates & Rotates Keys

Service	Who Creates	Where Stored	Rotation
Neon	DevOps (you)	.dev.vars + wrangler secrets	On leak or change
Supabase	DevOps (you)	public config + .dev.vars	On leak or change
R2	DevOps (you)	wrangler auth (via CLI)	On leak or change
Claude API	User only	.env (never in code)	Per-request or CLI
Gemini API	User only	.env (never in code)	Per-request or CLI

---

9. THIRD-PARTY INTEGRATIONS

Gemini API (Google AI)

• Use For: Text generation, image analysis, embeddings
• Cost: ~$0.075 per 1M input tokens, $0.30 per 1M output tokens
• Reference: /Users/hummingbird/Desktop/Laqta — complete Gemini integration

Claude API (Anthropic)

• Use For: AI features (chat, summarization, content generation)
• Models: Sonnet (capable), Haiku (fast), Opus (reasoning)
• Budget: Enforce at application level per month

Stripe (Credit Card Payments)

• Use For: USD/EUR payments
• Test Card: 4242 4242 4242 4242
• Webhook: /api/webhooks/stripe for payment confirmations

QiCard (Iraqi Mastercard Processor)

• Use For: IQD payments
• Key Difference: NO refund/pre-auth API (one-shot only)
• Test Card: Provided in integration docs

OTPIQ (OTP Provider for Iraq)

Channel	Cost (IQD)	Speed	Coverage
SMS (Zain)	250	~5 sec	Nationwide
WhatsApp	25	~2 sec	Nationwide
Telegram	20	~1 sec	Users only

---

10. GIT & CI/CD PATTERNS

Branch Naming Convention

feature/<name>        # New feature
bugfix/<name>         # Bug fix
hotfix/<name>         # Production urgent fix
refactor/<name>       # Refactoring, no feature change
docs/<name>           # Documentation only

Protected Main Branch Rules

1. Require pull request reviews (1+ reviewer)
2. Require branches be up to date before merging
3. Require status checks to pass (CI/CD pipeline)
4. Dismiss stale reviews when new commits pushed

Auto-Deploy Patterns

Project	Pattern	Auto-Deploy	Staging
Noor (JAT ERP)	Direct to production	Manual only	No
X-Grid	Feature → merge to staging	Yes to staging	Yes
Cinefolio	Feature → merge	No (manual review)	Yes
Classico Brief	Merge to main	Yes to production	No
Laqta	Merge to main	Yes to production	No

---

11. COMMANDS & SCRIPTS

Global Commands

# Project Tracker
~/Desktop/codeat-hub/track.sh list
~/Desktop/codeat-hub/track.sh show <id>
~/Desktop/codeat-hub/track.sh set <id> pct=85 phase=building

# Wrangler (Cloudflare)
npx wrangler deploy                              # Deploy to production
npx wrangler pages deploy dist                   # Deploy to Pages
wrangler pages secret put NAME VALUE             # Set secret
npx wrangler deployments list                    # Deployment history
npx wrangler rollback --deployment-id <id>     # Rollback

# Database
npx wrangler d1 execute --local "SELECT 1"       # Query local D1
npm run db:push                                  # Drizzle schema sync
npm run db:migrate                               # Drizzle migrations

Noor (JAT ERP) Project Commands

cd ~/Desktop/Noor

npx tsc --noEmit                  # Type check
npx eslint .                      # Linter
npm run test -- --run             # Unit tests (expect 344 passing)
node scripts/check-selectors.mjs  # Selector check (expect 21/21)
npm run deploy                    # Deploy to production
npm run deploy:staging            # Deploy to staging Worker
vite dev                          # Local dev

---

12. COMMON MISTAKES & FIXES

Mistake	Cost	How to Spot	Fix
🔴 Mock config shipped to live	Account takeover (OTP/payments)	Curl production: POST /api/auth/request returns a code	Move to .dev.vars; ship safe default
🔴 Tests hit production DB	Orphan notifications, account corruption	Print resolved host; re-run against staging	Add resolveTarget() check
Deploy code before schema migrates	500 errors on every query; live hangs	Service down after deploy	Migrate production THEN deploy code
Typecheck not run post-edit	Broken build ships to user	Compilation errors mid-session	Add PostToolUse typecheck hook
wrangler d1 execute --local while dev running	Stale data; writes vanish	Local queries work; deploy fails	Stop dev → reseed → restart
CSS @import after @tailwind	Site ships unstyled; build is green	Bundle suspiciously small; no CSS	Import from main.tsx; let Vite bundle
Pages secret race	Deploy gets old value; 403 on new secret	Immediate deploy after secret put fails	Set secret → wait 15s → deploy
R2 commands without --remote	Production untouched; success reported	Local message "Resource location: local"	Always pass --remote
Generated wrangler config shipped stale	Feature deployed but live is missing	Read bindings table wrangler prints	Deploy via npm run deploy
git checkout -- . in concurrent repo	Unrelated work reverted silently	Another agent reports changes disappeared	Never repo-wide discard; name the paths
Secret committed to tracked file	Leaked API key / DB password	Hook blocks write or audit finds in git	Add secret-scan hook; rotate secrets
Local dev vs deployed staging	Hours spent on false bug	Test passes deployed, fails local	Restart local dev; test deployed Worker

---

13. WRITING VOICE

Cut On Sight

• Em dashes → Use comma, period, or restructure
• Significance inflation — "stands as a testament to" → Say what happened
• AI vocabulary — delve, crucial, boast, foster, intricate, tapestry, landscape, pivotal, underscore, elevate, robust, seamless
• Negative parallelism — "Not just X, it's Y" → State directly
• Filler — "It is important to note that", "in order to" → Delete
• Generic closers — "the future looks bright" → End on something specific
• Copula avoidance — "serves as", "functions as" → "is"

Keep

• Contractions, varied sentence length
• Concrete numbers ("saved 40 minutes", not "significantly faster")
• Directness — say the thing

---

14. MEMORY REFERENCE FILES

Master index: /Users/hummingbird/.claude/projects/-Users-hummingbird/memory/MEMORY.md (100+ files)

🔴 Critical Lessons (8 Incidents)

• shipped-config-must-be-safe.md — Mock OTP shipped to live URLs
• tests-hit-production.md — Seeded 10 live accounts, allocated 50M IQD
• silent-failure-pattern.md — Defensive code hiding bugs
• cloudflare-d1-pages-gotchas.md — 8 D1 silent-failure traps
• workers-pbkdf2-cap.md — PBKDF2 100k iteration cap on Workers
• measure-after-deploy-propagates.md — Propagation delay after deploy
• chrome-headless-arabic-pdf.md — --headless=new required for Arabic
• hidden-tab-freezes-transitions.md — Unpainted tab pins timeline

Active Projects (Live Services)

• classico-erp.md — Material 3 Arabic/RTL ERP
• wain-events-directory.md — Material 3 + D1, LIVE
• noor-erp-rebuild.md — JAT core, LIVE
• qiran-matrimonial.md — LIVE, runs verify-safety.sh
• laqta-photography-saas.md — Gemini AI, LIVE
• elite-trainer-app.md, elite-mobile-app.md, elite-admin-app.md

Architecture & Patterns

• core-2.0-dashboard-skill.md — Tokens + primitives, NOT composition
• default-design-system-material.md — Material 3 is default
• erp-builder-skill.md — Reproduce Noor per client
• figma-mcp-constraints.md — Hard prerequisites (desktop app, Dev Mode, paid seat)