New contributor onboarding

You just got access to the WiqAIa+ codebase. This page gets you from “fresh clone” to “ready to pick up an issue” in about 30 minutes.

If you’re here to read about what we’re building rather than how to set up, jump to the Plan Overview instead.

What you should already have

• A Gitea account at git.rizoma.sa with an SSH key (or HTTPS personal access token) configured.
• Read access to rizoma/wiqaia. If you can open https://git.rizoma.sa/rizoma/wiqaia, you have it.
• A short briefing from Melissa on which role you’re filling — cloud engineer or AI/ML engineer.

If any of these are missing, ask Melissa before going further.

1. Prerequisites on your machine

Install these once. Versions matter — older versions might work but aren’t tested.

Linux / WSL is the supported environment. macOS works for most things; expect to hit the occasional path-or-permissions hiccup. Windows-native isn’t tested.

2. Clone the repo

git clone https://git.rizoma.sa/rizoma/wiqaia.git
cd wiqaia

The repo is a pnpm monorepo with Turborepo for task orchestration. Apps live in apps/, shared code in packages/, infrastructure in infra/, and the docs site you’re reading in apps/docs/.

3. Install workspace dependencies

pnpm install

This does several useful things automatically:

• Installs all workspace dependencies (~1-2 minutes the first time).
• Installs the pre-push git hook via the root prepare script. From now on, git push runs the full test + lint + typecheck gate locally before sending anything to the server. Details in step 7.
• Symlinks workspace packages — @wiqaia/contracts is consumable from any app under apps/ immediately.

4. Verify your setup

Run the contracts test suite — it exercises TypeScript, Python, and Go together, so if all three pass you’re set up correctly:

pnpm -F @wiqaia/contracts test

You should see 12 tests pass across three languages. If something fails, it’s almost always one of:

• go: command not found — Go isn’t on your PATH. Add $HOME/go-toolchain/bin (or wherever you installed it) to your shell profile.
• No module named google.protobuf — Python protobuf not installed. pip install --user protobuf pytest (use --break-system-packages on newer Debian/Ubuntu).
• TypeScript errors — usually means pnpm install didn’t finish; re-run it.

If you can’t get this to pass, ask in the team channel before spending more than 20 minutes on it.

5. Read these, in order

About 60 minutes of reading. Skim where you’re already familiar.

1. Plan Overview — strategic frame, principles, milestone roadmap. The mental model for everything.
2. Architecture Summary — locked-in tech stack and rationale per choice.
3. Cost Guardrails — non-negotiable if you’re going to touch GCP.
4. Data Protection — encryption, RLS, audit, NCA/PDPL alignment.
5. Abstractions & Contracts — the interface boundaries every driver implements.
6. Your role-specific milestone docs — see below.

If you’re the cloud engineer hire, your first read after the foundations is M01 Foundations. Then the Managing quotas runbook, since that’s already half-built.

If you’re the AI/ML engineer hire, read M05 Edge AI and M06 Cloud LLM before anything else.

The Contributor Brief (in the repo, not on this site) has your role’s deliverable list — what you’re being asked to produce.

6. Find your first issue

We track work in Gitea milestones + issues, mirroring the plan milestones 1:1. Open https://git.rizoma.sa/rizoma/wiqaia/issues?state=open and filter by your track label:

• Cloud work: cloud label
• AI work: ai label
• Backend: backend label
• Frontend: frontend label
• Edge: edge label
• Critical-path-only: critical-path label

needs-human issues are external dependencies — confirming a fire-panel model, getting NVR access, etc. — that block specific work but typically aren’t engineering tasks. Skip them unless explicitly assigned.

Pick something not labeled needs-human, drop a comment that you’re starting it so someone else doesn’t double-up, and go.

The Issue tracking runbook has the full conventions — how labels work, how milestones map to plan, why we deliberately don’t use PR auto-linking or project boards.

7. Day-to-day workflow

Branches and commits

We’re trunk-based right now. Push to master. The pre-push hook is the gate; there’s no PR-review step yet (we’ll add it when the team grows). Commit messages follow the existing style — read git log --oneline for examples. Roughly:

<scope>: <one-line summary, lowercase, no period>

Multi-line body explaining *why*, with concrete details about *what*
changed where. Reference issues with #N (no auto-link, deliberate).

The pre-push hook

Every git push runs locally before bytes leave your machine:

$ git push origin master
[hook]  ▸ Static validation (verify.py + dockerfile paths + md links)
[hook]    ✓ static checks pass
[hook]  ▸ Terraform fmt -check + validate (pilot-prod env)
[hook]    ✓ terraform clean
[hook]  ▸ Workspace tests (pnpm -r test)
[hook]    ✓ workspace tests pass
[hook]  ▸ Workspace typecheck (pnpm -r typecheck)
[hook]    ✓ typecheck pass
[hook]  ✓ All pre-push checks passed.
[git]   Pushing to remote...

Anything red → push aborts, fix locally, retry.

Smart skips: a docs-only diff skips the heavy checks (the post-receive deploy already validates the built doc site).

Escape hatch — git push --no-verify skips the gate. Use it when you’re confident the gate is wrong (e.g., a flaky test). Don’t use it because you’re in a hurry.

The hook itself lives at scripts/git-hooks/pre-push. It’s version-controlled — improve it via PR like any other code. Git is configured to use that directory (instead of .git/hooks/) via core.hooksPath, set automatically by pnpm install.

When something breaks

Where to ask questions

Team channel (Slack equivalent — TBD as the team forms). For anything load-bearing, mention Melissa directly.

8. Things to not do

Short list of immediate ways to cause headaches:

• Don’t commit .tfvars files. Real ones contain billing account IDs, alert emails, etc. The .gitignore covers *.tfvars — keep it that way. Use terraform.tfvars.example as the template.
• Don’t push customer frames, video, or BIM files into the repo. The apps/edge-app/ test fixtures use synthetic data only.
• Don’t commit secrets of any kind. Use Secret Manager at runtime. .env for local dev only, gitignored.
• Don’t run terraform apply without explicit approval. The wiqaia (pilot) project is deliberately blank — quotas are live but nothing else. First apply is gated on the cloud-ops Terraform review (issue #28).
• Don’t use Vertex AI, OpenAI, Anthropic API, or any external AI API on code paths that process customer data. Inference is in-Kingdom only.

You’re set

If you’re past step 4 with green tests and you’ve read at least the Plan Overview, you’re ready to pick up an issue.

If anything in this page is wrong or unclear, fix it. The doc lives at apps/docs/src/routes/onboarding/+page.md; edit, run pnpm -F @wiqaia/docs build, commit, push — it goes live in under a second. See Maintaining the docs if you want the full mechanism.