1 files changed, 163 insertions, 0 deletions
diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md
new file mode 100644
index 0000000..78503f4
--- /dev/null
+++ b/docs/07-developers/onboarding-and-standards.md
@@ -0,0 +1,163 @@
+# Developer Onboarding, Standards, and Tools
+
+> Everything a new contributor needs: what to read, how to build and test, how
+> we write code, and how to land a change.
+
+## 1. Your first day
+
+### 1.1 Reading order (about 3 hours)
+
+1. [`../README.md`](../README.md) — the project front door (20 min).
+2. [`../01-orientation/01-purpose-and-scope.md`](../01-orientation/01-purpose-and-scope.md)
+   and [`../01-orientation/02-the-ai-edge-and-ecosystem.md`](../01-orientation/02-the-ai-edge-and-ecosystem.md)
+   — why the project exists (30 min).
+3. [`../03-architecture/01-system-overview.md`](../03-architecture/01-system-overview.md)
+   — the architecture in one document (30 min).
+4. [`../03-architecture/06-host-module-and-hybrid-model.md`](../03-architecture/06-host-module-and-hybrid-model.md)
+   — where the code lives (30 min).
+5. [`../04-implementation/01-known-knowns-and-unknowns.md`](../04-implementation/01-known-knowns-and-unknowns.md)
+   — what to work on and what is hard (30 min).
+6. The subsystem doc for whatever you plan to touch.
+
+### 1.2 Environment
+
+```bash
+git clone https://git.vgpu.io/open-iov.git
+cd open-iov
+./install.sh deps nvidia firmware build   # full setup
+./scripts/stack_manager.sh up             # + load + create mdev
+./scripts/stack_manager.sh test           # host test suite
+```
+
+You will need: a supported NVIDIA GPU, IOMMU-enabled host, hugepages, kernel
+headers, QEMU, and (for guest work) a Linux guest with the stock driver.
+
+### 1.3 The daily loop
+
+```bash
+make kernel                    # kernel module (generates Module.symvers)
+./scripts/stack_manager.sh build-kernel
+./scripts/stack_manager.sh load-open-iov
+./scripts/stack_manager.sh mdev-create
+./scripts/vgpu_vm.py start vgpu-linux
+# guest work ...
+./scripts/stack_manager.sh dmesg        # live trace
+```
+
+When you change kernel code, remember: reload requires removing the mdev and
+the VM holding it. The stack manager enforces the order.
+
+## 2. Repository map
+
+```
+open-iov/
+├── kernel/               host module (GSP emulation, device model, memory model)
+├── userspace/            management library + examples
+├── tools/                debugging and analysis tools (guest-diag, rmq,
+│                         firmware analysis wrappers)
+├── scripts/              build/load/test automation, VM harness
+├── config/               hardware/version profiles (the portability surface)
+├── firmware/             versioned firmware images + decompilation artifacts
+├── (private)             reverse-engineering study notes live untracked;
+│                         see the maintainers' study index
+├── docs/                 THIS documentation tree (start at docs/README.md)
+└── wiki/                 long-form firmware/protocol deep dives
+```
+
+## 3. Coding standards
+
+### 3.1 Kernel module (`kernel/`)
+
+* Linux kernel C style (tabs, 80-column-ish, `checkpatch` clean where
+  practical).
+* **No comments explaining *what* the code does — comments explain *why*,
+  especially protocol quirks.** Our code encodes observations from hardware;
+  the observation must be recorded next to the code that depends on it.
+* Every handler logs its request/reply in a reconstructible form (the
+  trace-first policy). A handler that silently succeeds is an anti-pattern.
+* Never trust guest input: validate sizes, handles, indices, and sequences.
+  A malformed element must not be able to steer a write outside guest memory.
+* Memory: `kmalloc`/`vzalloc` per the use; DMA access through the hypervisor
+  interface only.
+* Error paths: fail closed, log once with context, and give up the device
+  cleanly.
+
+### 3.2 Userspace and tools (`userspace/`, `tools/`, `scripts/`)
+
+* C: same style as the kernel module where practical.
+* Python/shell: `shellcheck` clean shell, `python3` with no exotic
+  dependencies; scripts must be re-runnable and idempotent.
+* Tools must live **in-tree** (never in `/tmp`) so they survive reboots and
+  are reviewable.
+
+### 3.3 Documentation
+
+* Every behaviour change updates the doc that describes it. Docs are part of
+  the definition of done.
+* Prefer a table or a decision tree over prose for anything an operator will
+  follow under pressure.
+* Protocol facts (IDs, offsets, structures) must cite their source
+  (the decompiled study notes, or a live trace).
+
+## 4. Tooling
+
+| Tool | Purpose |
+|---|---|
+| `scripts/stack_manager.sh` | build/load/status/test/unload with correct ordering |
+| `scripts/vgpu_vm.py` | VM lifecycle incl. guest-agent exec/shell |
+| `tools/guest-diag/` | guest-side diagnostics (ptrace tracer, engines, probes, push helper) |
+| `tools/firmware_analyzer.py` + Ghidra scripts | firmware analysis pipeline |
+| module debug parameters | guest-memory scanning/poking, VRAM inspection |
+| QEMU gdbstub workflow | guest virtual-memory inspection/writing |
+| `wiki/` documents | protocol and firmware deep dives |
+
+## 5. Landing a change
+
+1. **Pick from the known-unknowns list** or a bug with a reproduction.
+2. **Reproduce** with the standard captures; write the decision tree if new.
+3. **Implement** with tests: host-side unit tests where possible; a scripted
+   guest scenario where not.
+4. **Evidence**: attach the rung-ladder result (see the evaluation doc) and
+   the before/after trace excerpt.
+5. **Docs**: update the affected documents (including the known-unknowns entry
+   if you closed one).
+6. **Review**: a reviewer must be able to reproduce your evidence from the
+   PR description alone.
+
+## 6. Makefile targets
+
+```bash
+make kernel        # open-iov-vfio.ko (first!)
+make nvidia        # NVIDIA OpenRM modules with KBUILD_EXTRA_SYMBOLS
+make userspace     # libiov.so, examples
+make all           # in the correct order
+make clean
+```
+
+## 7. Testing discipline
+
+* Kernel changes: at minimum, load/unload cycle ×3, mdev create/destroy, and a
+  guest boot + `nvidia-smi`.
+* Protocol changes: diff the RPC inventory before/after; attach both.
+* Memory-model changes: re-run the VA↔PA discovery tooling and a guest CUDA
+  start-up; attach the trace.
+* Never land a change that makes a rung regress, even "temporarily".
+
+## 8. Security hygiene for contributors
+
+* Do not add code paths that map or copy memory outside the hypervisor-provided
+  DMA interface.
+* Treat guest input as hostile; treat debug parameters as privileged.
+* If you add a debug surface, document it in the debugging doc and gate it.
+* If you discover a protocol fact that implies a security-relevant assumption
+  (e.g. "the guest can ask us to write anywhere"), stop and escalate: it is a
+  design issue, not a code issue.
+
+## 9. Getting unstuck
+
+* Start with the guest's own diagnostics (it is the oracle).
+* Then the host trace; the answer is almost always in the last RPC before the
+  failure.
+* Then memory observation (scan/poke) — but write down what you learn; the
+  next person needs it.
+* Ask in the project channels with a *reproduction*, not a summary.