docs/07: state the actual userspace C style; record de facto conventions

Section 3.2 documented 'same style as the kernel module where practical',
which the sources contradicted (4-space indentation throughout). It now
states the real rules: 4-space/~100-col C, snake_case/_t naming, include
guards, status-type error handling, existing set -e/pipefail and SPDX
practice. New section 3.4 records conventions that were only implicit:
commit-message format with ISSUE-0001 refs, doc Status/change markers,
config/ and firmware/ layout, and the per-file SPDX enforcement point.

1 files changed, 48 insertions, 2 deletions

diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md
index ef6388e..ee4c2b9 100644
--- a/docs/07-developers/onboarding-and-standards.md
+++ b/docs/07-developers/onboarding-and-standards.md
@@ -123,9 +123,27 @@ The following rules each come from a real bug and are enforced in review:
 
 ### 3.2 Userspace and tools (`userspace/`, `tools/`, `scripts/`)
 
-* C: same style as the kernel module where practical.
+* **C: 4-space indentation, ~100 columns** — deliberately *not* the kernel
+  style. This is the style the existing sources use (`libvgpu.c`,
+  `rpc_emulator.c`, the test binaries); the per-area configs are
+  `userspace/.clang-format` and `tools/.clang-format` (LLVM base). Do not
+  mass-reformat existing files; the config governs new code and hunks you
+  are already editing.
+* C naming and structure: `snake_case` functions and structs
+  (`gsp_alloc_args`, `rpc_emu_bar_config`), types as `*_t`
+  (`vgpu_error_t`), `_LIBVGPU_H_`-style include guards, and prototypes in
+  the matching header with `extern "C"` for the public API.
+* C error handling: return the library's status type (`vgpu_error_t`), not
+  raw `errno`; translate at the syscall boundary (`map_errno`), check every
+  allocation and return value, and fail closed. No `abort()`/`exit()` in
+  library code — the caller owns the error.
+* Every C/Python/shell source file starts with
+  `SPDX-License-Identifier: BSD-3-Clause` plus a one-line copyright;
+  kernel sources use `GPL-2.0` instead. Per-file identifiers govern (see
+  [`../README.md`](../README.md) §7).
 * Python/shell: `shellcheck` clean shell, `python3` with no exotic
-  dependencies; scripts must be re-runnable and idempotent.
+  dependencies; scripts must be re-runnable and idempotent. Shell scripts
+  start with `set -e`; operational scripts use the full `set -euo pipefail`.
 * Tools must live **in-tree** (never in `/tmp`) so they survive reboots and
   are reviewable.
 
@@ -145,6 +163,34 @@ The following rules each come from a real bug and are enforced in review:
   offset are 0x100000 too low (the wrong functions) — re-derive any conclusion
   drawn from them.
 
+### 3.4 Tracked conventions (de facto)
+
+These are the practices review already expects; they are written down so new
+contributors do not have to infer them.
+
+* **Commit messages**: `<subsystem>: <description>` — an imperative,
+  lower-case subsystem token (`vgsp`, `vgsp-rm`, `sema`, `guest-diag`,
+  `scripts`, `tools`, `debug/issue`), then what changed. Cite issues inline
+  as `(ISSUE-0001)`; the register is
+  [`../../debug/issue/README.md`](../../debug/issue/README.md). Commit
+  messages are public: describe behaviour and evidence (same rule as tracked
+  docs).
+* **Document status and change markers**: long-lived deep-dive documents open
+  with a `> Status: ...` preamble under the H1 and append a
+  `<!-- change (YYYY-MM-DD): ... -->` comment recording substantive edits —
+  see
+  [`../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md`](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md).
+* **Config and firmware layout**: `config/hardware/` holds per-architecture
+  profiles and `config/versions/` per-driver-version profiles — portability
+  work is a config change before it is a code change. A versioned firmware
+  tree is `firmware/<SERIES>-GSP/<MAJOR.MINOR>/` (images fetched by
+  `install.sh`; analysis artifacts tracked). See
+  [`../06-portability/hardware-software-matrix.md`](../06-portability/hardware-software-matrix.md).
+* **SPDX enforcement point**: the per-file `SPDX-License-Identifier` governs
+  a file's license regardless of its directory; every new source file must
+  carry one (BSD-3-Clause for userspace/tools/scripts/docs, GPL-2.0 for
+  `kernel/**`).
+
 ## 4. Tooling
 
 | Tool | Purpose |