[docs] The jtrm-*.md files cite source code as their source — the authority chain is circular

[JoeMatt]

Found during the #513/#514 controller spike (PR #521), which hit it directly: the spike needed TR10's joystick-matrix section, went to docs/jtrm-jerry.md §"Joystick Interface" as CLAUDE.md instructs, and found it cites src/jerry/joystick.c as its source.

The problem

CLAUDE.md makes two claims about these files:

Authoritative hardware reference: The Jaguar Technical Reference Manual (JTRM) is the ground-truth spec for all emulation decisions.
docs/jtrm-*.md — synthesized from the Jaguar Technical Reference Manual... Read these before making hardware-accuracy decisions. They supersede comments in source code.

And warns, correctly, that source comments in this tree have been wrong for years at a time — the PIT clock rate being the standing example.

But 21 of the 23 Source: lines across docs/jtrm-*.md cite source files, not the manual:

file	cites source code
jtrm-jerry.md	10 / 10
jtrm-gpu-dsp.md	5 / 5
jtrm-clocks-timing.md	3 / 4
jtrm-object-processor.md	2 / 2
jtrm-blitter.md	1 / 2

So for most sections the authority chain is circular: the doc that is supposed to validate the implementation was derived from the implementation. A wrong constant in jerry.c would be faithfully copied into jtrm-jerry.md and then cited back as the manual's word — which is exactly the failure mode the JTRM-over-comments rule exists to prevent.

This is not hypothetical. The spike found that docs/lightgun-design.md had recorded a Team Tap assumption as "plausible, not TR10-confirmed", and reading TR10 directly showed the assumption was backwards (the adapter wire-ORs the B0/LP line rather than isolating it). Direct manual reads change answers.

What is not wrong

The content may well be correct — much of it probably is, and jtrm-register-map.md has no Source: lines at all. The defect is provenance, not necessarily accuracy. Nothing here should be deleted on suspicion.

Suggested fix, cheapest first

1. Relabel honestly. Change Source: src/foo.c to something that does not claim manual authority — e.g. Derived from: src/foo.c (NOT verified against the JTRM). Pure documentation change, no research, and it immediately stops the docs from over-claiming.
2. Verify the load-bearing sections against the PDFs and upgrade those citations to page references, the way jtrm-blitter.md:85 and jtrm-clocks-timing.md:62 already do (JTRM v8 pp. 66, 70-71, JTRM Rev 10 p.8). Those two lines are the model.
3. Prioritise by risk: clocks/timing and the interrupt/register sections are the ones an accuracy decision actually turns on.

Read the PDF pages as rendered images where a table is involved. The spike found pdftotext reorders columns in TR10's 16-row matrix table, which would have produced a confidently wrong transcription.

Note for agents and sessions

Until this is fixed, "the JTRM docs say X" is not by itself sufficient grounds for a hardware-accuracy change when the relevant Source: line points at source code. Check which kind of citation you are standing on.

[JoeMatt]

There is a corollary to the circular sourcing that is worse than the circularity itself, and #538 just demonstrated it.

Because 21 of 23 Source: lines cite source files, the distilled docs were effectively synthesised from the implementation rather than from the manual. That has a structural consequence:

docs/jtrm-*.md can only describe hardware we already emulate. It is therefore incapable of telling you about hardware we have not implemented — which is exactly when someone consults it.

Concretely, the entire controller surface of jtrm-jerry.md is this:

## Joystick Interface
| $F14000 | JOYSTICK | RW | Joystick/keypad data (active-low, muxed) |
| $F14002 | JOYBUTS  | RO | Fire buttons A, B, C, Option, Pause      |
...mux description, ~6 lines...
Source: src/jerry/joystick.c

18 lines. Meanwhile Technical Reference V10 (which we hold at docs/atari-jaguar-1999/Technical Reference v10.pdf) devotes a whole chapter to controllers, none of which appears in our docs:

TR10 section	in jtrm-*.md?
Standard Jaguar Controller Matrix (the 16 socket/row codes)	❌
Rotary "Tempest" Controller	❌
4-Player Adaptor (Team Tap), incl. port behaviour with/without	❌
Analogue Joystick or Driving Controller	❌
Keyboard / Mouse	❌
Advanced Controllers (bank protocol, 100 µs row-0 rule, identification pass, current budget)	❌
6D Controller (6 DOF, 3 banks, 55 bits)	❌

Three casualties so far, all avoidable

1. [feat] Team Tap support — the 4-player adapter is not emulated #513 (Team Tap) — the spike needed the socket/row table, went to jtrm-jerry.md as CLAUDE.md instructs, found a source-code citation, and ended up reading TR10 p.18 as a rendered page image because pdftotext column order could not be trusted. That is the failure this issue was filed for.
2. [feat] Pro Controller support — the six-button pad is not emulated #514 (Pro Controller) — searched the SDK set and found nothing, because Atari's docs call it the "4 Player Adaptor", not "Team Tap". A manual-sourced controller doc would have carried both names.
3. [feat] 3D flight stick with 6 degrees of freedom #538 (6D controller) — a user had to link an external copy of a PDF we already have, to point at a spec our own distilled reference omits entirely.

Suggested shape of the fix

Beyond re-sourcing the existing 23 lines, add docs/jtrm-controllers.md covering the TR10 controller chapter in full, sourced to page numbers in TR v10, and explicitly including devices we do not emulate (6D, keyboard/mouse) marked as such. The value of a hardware reference is highest exactly where the code is silent.

Two things worth encoding while doing it:

• Cite the document and page, never a .c file. Where behaviour is emulator-specific, label it "emulation note", clearly separated from spec.
• Note which TR revision. TR v8 and 04 - Technical Reference.pdf do not contain the controller chapter; only v10 does. Anyone verifying against the wrong revision will conclude the spec does not exist — which is very close to what happened in [feat] Pro Controller support — the six-button pad is not emulated #514.