[DOCS] Write down the cross-compilation promise (README + installation docs), with explicit support-status tags

See also:

• https://github.com/crossbario/zlmdb/issues/145
• https://github.com/crossbario/crossbar/issues/2280

---

Why

PR #1934 proposed changing NVX compiler-flag selection for external cross toolchains (Yocto/OpenEmbedded, Buildroot). Reviewing it surfaced a more basic problem:

we cannot say whether that PR fixes a deviation from promised behaviour, because we never wrote the promise down.

Where cross-compilation is mentioned today:

• docs/changelog.rst:70 (#1834/#1835) — "The default architecture target is now the portable baseline for all build contexts (wheels, local source installs, and cross-compilation). The target architecture is detected via sysconfig.get_platform() so the correct baseline is chosen when cross-compiling."
• src/autobahn/nvx/_compile_args.py module docstring — "never hands a cross-compilation toolchain the host-only -march=native flag" and, at :238-240, "Defaulting to 'safe' rather than -march=native is what makes cross-compilation work out of the box". This is published — via sphinx-autoapi, despite the leading underscore.

Where it is not mentioned: README.md, docs/installation.rst, or anywhere else a user or integrator would look. Grepping the docs tree returns hits only in the changelog, _compile_args.py and its test.

So an integrator has to discover our cross-build behaviour by hitting a compiler error. Meanwhile the docstring makes the strongest claim we have — "works out of the box" — with no CI job that cross-compiles anything behind it. That claim is aspiration, not fact, and it is published as documentation.

This issue is about fixing the promise, not the code.

Support-status vocabulary (to be used identically in autobahn, zlmdb, crossbar)

• Supported — named targets, gated in CI: Tier 1 per-commit, Tier 2 nightly.
• Best-effort — expected to work, not gated in CI; bug reports welcome.
• Roadmap — intended direction, not yet backed by tests.

Test tiers (vocabulary, for the docs; implementation is out of scope here)

• Tier 1 — cross-build ("baking"): the native extension cross-compiles for the target and the artifact is verified (e.g. readelf -h → expected machine, plus an import/functional smoke test of the built module). Fast; intended to
  run on every commit.
• Tier 2 — run on target: boot the target (QEMU system emulation) and run the project's own test suite there. Slow; intended to run nightly.

Reference target for both tiers: riscv64 (rv64gc / lp64d) via Buildroot, cross-built on x86-64, glibc first and musl second, booted under qemu-system-riscv64. riscv64 is deliberately chosen: it is a true cross-build
(our aarch64 wheels are built natively under QEMU-user, which never exercises the cross path at all), and we publish no riscv64 wheels, so every riscv64 user must build from source.

The matrix to publish

artifact	Tier 1 (cross-build)	Tier 2 (run on target)
autobahn	roadmap → supported once the job lands	roadmap
zlmdb	roadmap → supported once the job lands	roadmap
crossbar	roadmap	roadmap (ultimate goal)

Rows move up as tiers land. Nothing may claim more than it can demonstrate.

What to write

1. README.md — a short "Cross-compilation and embedded targets" subsection stating the promise and its current status tag, linking to the installation docs. This is a top-level promise; it should not be buried.
2. docs/installation.rst — the substance:
   • what we guarantee today: with AUTOBAHN_ARCH_TARGET unset we never emit a host-specific -march (in particular never -march=native); the architecture baseline is chosen from the target as reported by sysconfig.get_platform(); unknown/unrecognised targets get no -march at all and the toolchain's own flags govern code generation;
   • the documented escape hatch: AUTOBAHN_ARCH_TARGET=native|safe, what each means, and when a distro/integrator should set it;
   • the status tags per target, per the matrix above;
   • a note that Buildroot/Yocto-class toolchains supply their own -march/-mtune/-mcpu, and what we do about that (see the open decision below).
3. Fix the overclaim in src/autobahn/nvx/_compile_args.py:238-240: "what makes cross-compilation work out of the box" → wording that matches what we actually back. This text is published via autoapi, so it is a promise whether we meant it as one or not.

Open decision to record while writing this

#1934 implicitly invented a precedence rule that we have never stated. Writing the docs forces the question, and the answer belongs in installation.rst:

What is authoritative about the target architecture? Explicit
AUTOBAHN_ARCH_TARGET > a cross toolchain signal (CC/CROSS_COMPILE) >
sysconfig.get_platform()?

This matters because the underlying report in #1934 is that sysconfig.get_platform() returned the host (linux-x86_64) under Yocto while targeting ARM — i.e. the mechanism our changelog names as the guarantee failed, one layer below where #1934 patches. Whatever we decide, an explicit "we do not second-guess an externally managed toolchain" rule (or its opposite) must be written down before any code change implements it. Tracked separately; see the companion issue for the sysconfig target-detection bug.

Non-goals (separate issues, to be filed later)

• Implementing the Tier 1 / Tier 2 CI jobs.
• Factoring shared cross-build CI machinery into wamp-cicd.
• Changing _compile_args.py behaviour (beyond correcting the overclaiming
  docstring text).

Acceptance criteria

• README.md carries a cross-compilation / embedded-targets subsection with
  an explicit status tag
• docs/installation.rst documents the guarantee, the
  AUTOBAHN_ARCH_TARGET escape hatch, the per-target status tags, and the
  Tier 1 / Tier 2 definitions
• The _compile_args.py "works out of the box" claim is corrected to match
  what is actually backed
• Every claim in the new text is either backed by an existing test or
  explicitly tagged roadmap — no unbacked assertions
• The status vocabulary and matrix are worded identically to the
  corresponding zlmdb and crossbar issues

Start with README.md, docs/installation.rst, and the published wording in src/autobahn/nvx/_compile_args.py around lines 238-240; inspect the existing cross-compilation references and related test. Record the authoritative target-detection rule and align the status vocabulary and matrix with the linked zlmdb and crossbar issues. Done means the requested documentation and overclaim correction are complete, with unsupported claims marked roadmap.