docs(dev): replace the impossible venv recipe with the verified one

[lusoris]

Summary

docs/development/languages.md told developers to run python3 -m venv .venv && pip install -e ".[dev]" at the repo root. That cannot work: the root pyproject.toml has no [build-system] and no [dev] extra — it is only Black/Ruff/pytest/mypy configuration for a package named vmaf-fork-tooling — so pip fails with Multiple top-level packages discovered in a flat-layout. Verified by running it in a throw-away venv (probe output in the commit trail).

The page now carries the recipe that was actually verified on 2026-09-04 (Python 3.14, golden gate 271 passed / 12 skipped / 0 failed afterwards): per-package editable installs — python/, mcp-server/vmaf-mcp, tools/vmaf-tune[fast], dev-llm, with ai[dev] as the heavy optional — cross-checked against the canonical list in dev/Containerfile:1037-1047, and with meson pinned to 1.12.0 because every meson build dir hard-codes the absolute path of the meson that configured it. It also gains a short "recovering a destroyed venv" note (symptom, cause, recipe) for anyone hit by the .venv symlink that #1280 removed.

The two other pip install -e . occurrences under docs/mcp/ are cd mcp-server/vmaf-mcp && pip install -e . — per-package, correct, left alone. Mentions inside Accepted ADRs and research digests are historical records and are not edited.

Also in this PR: one stale line in docs/development/rust.md

Found by the 2026-09-04 gap triage (#1270, verdict STALE, verified against master): the page said a higher-level vmafx crate "is planned for a future PR", but bindings/rust/vmafx has existed since ADR-0929 (PR #859). Same subsystem (docs/development/), one-line correction, so it rides here rather than as its own PR.

Type

• docs — documentation only

Checklist

• Commits follow Conventional Commits.
• make format && make lint is green locally (markdownlint via pre-commit, no --fix).
• Unit tests pass — n/a, docs only. The recipe itself was exercised: every install step returned 0 and the Netflix golden gate ran green on the resulting venv.
• SIMD/GPU, twins, new C sources, breaking change, ADR — all n/a.

Bug-status hygiene (ADR-0165)

• docs/state.md — no row needed: documentation-only change with no code defect; the incident behind the recovery note is already recorded under T-VENV-SYMLINK-TRACKED-2026-09-04 (fix(repo): untrack the .venv symlink that #1231 committed, and gate against it #1280).

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: trivial. The old recipe fails on first run; the new one is the container's own install list.
• Decision matrix — no alternatives: only-one-way fix. There is no root package to install; per-package installs are the only recipe the tree supports.
• AGENTS.md invariant note — no rebase-sensitive invariants: docs/development/ is fork-added.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/venv-recipe-docs.md.
• Rebase note — no rebase impact: docs/development/ is fork-added with no upstream counterpart (recorded in docs/rebase-notes.md).

Reproducer

mkdir -p probe && python3 -m venv probe/venv && probe/venv/bin/pip install -e ".[dev]"
# -> error: Multiple top-level packages discovered in a flat-layout: ['ai', 'dev', 'cmd', ...]

🤖 Generated with Claude Code