These files are hand-maintained, not generated, and had drifted
from the implementation:

- tutorial.md described the pre-v41 LogicSig world. It now covers
  the four signature methods including post-quantum signatures,
  the LMsig and PQsig LogicSig fields and how they bind the
  authorizer's address into the signed message, that at most one
  delegation signature may be present, that validation is against
  the authorizer (AuthAddr when rekeyed), and that legacy Msig is
  rejected from consensus v41 onward, with goal's --legacy-msig
  escape hatch. Also fixes the "LogicSic" typo.
- jsonspec.md conflated rules that json_ref enforces while parsing
  the whole text with rules enforced only on the extracted value.
  Classify each rule as whole-text or extraction. In particular,
  the old "Raw non-unicode characters not accepted" claim was
  wrong: invalid utf-8 parses, and becomes U+FFFD when a string
  value containing it is extracted. A \u escape with non-hex
  digits parses but errors on extraction (it becomes U+FFFD only
  in a key), and a null value parses but always errors on
  extraction.
- TestParseRawNonUnicodeChar never tested invalid utf-8 (its input
  was valid utf-8 and its error cases failed for other reasons).
  It now feeds a genuine invalid byte through parse and extraction
  and asserts the U+FFFD replacement.
- README.md points at the generated stack-types table and lists
  the assembler pseudo-ops (int, byte, addr, method) that appear
  in no opcode table.

Document behavior that the descriptions omitted or got wrong:

- The v13 box opcodes: shared boxAccessExtra text states the name
  length rule (1-64 bytes, MaxAppKeyLen), the availability rule,
  and the ClearState ban for every box opcode, not only those
  whose short description mentioned them. foreignBoxExtra spells
  out the app_box_* authorization matrix (AppForeignBoxReads for
  reads, AppFamilyBoxAccess plus same creator for everything
  else) and the family reentrancy rule; boxFamilyExtra applies the
  same reentrancy rule to an app's own boxes once it opts in.
  app_params_set explains what setting each flag grants.
- itxn_begin's Fee description matched neither the group-based fee
  logic nor when fees are checked. Describe the actual default:
  the amount that would make the group's fees sufficient so far,
  with the new transaction counted as one base fee, and note that
  the real check happens at itxn_submit.
- bnz documents the v13 varint offset encoding (previously it
  described only the two-byte form), including the forward/back
  reference points and that a branch to the start of its own
  instruction cannot be encoded. callsub points at bnz for the
  encoding.
- State failure conditions: shl/shr fail if B > 63, divmodw fails
  on a zero divisor, bzero fails above 4096.
- balance/min_balance params claimed an application id argument
  they do not take. voter_params_get and online_stake answer as of
  the balance round (320 rounds back), not the agreement round.
- json_ref links to the JSON spec by URL (the relative link only
  worked in the repo) and assorted typo/spacing fixes, including
  the ec_multi_scalar_mul naming note that compared the opcode to
  itself.

The ArgEnum table in langspec was built from a hand-maintained
switch on opcode names, which had drifted from reality: ec_add and
the other ec_* opcodes, mimc, poseidon2, voter_params_get, itxnas,
and gitxnas had field groups but no documented enum. Derive the
enum from the field group attached to the spec's immediates
instead, so a new opcode with a FieldGroup is documented without
anyone remembering to update opdoc. itxn_field keeps an explicit
override because its spec deliberately carries the full TxnFields
(for assembler errors) while only the settable fields belong in
the docs.

Consequently the txn-family opcodes (txn, gtxn, gtxns, itxn,
gitxn) no longer list array fields in their ArgEnum. That is more
accurate: their single-immediate forms reject array fields at
assembly, and the array opcodes (txna et al.) still list them.
Downstream langspec consumers will see this change.

Other opdoc fixes:
- fieldGroupMarkdown exits nonzero on an undocumented field, as
  integerConstantsTableMarkdown already did, instead of emitting
  an empty NOTES cell. This is how every block field shipped
  undocumented.
- docVersion comes from ConsensusCurrentVersion's LogicSigVersion
  instead of a hardcoded 13, so it tracks future promotions
  without publishing vFuture opcodes.
- avm-appendix-a.md is written by opdoc for the newest version,
  rather than the Makefile picking a file out of a glob, which
  could not tell a stale TEAL_opcodes_v99.md from a real one.
- The Makefile no longer claims the hand-maintained README.md as a
  generated target, and clean removes all doc intermediates.
- .gitignore explains the intermediate scheme and negates the
  hand-written markdown files so new ones are visible to git add.

Several field groups shipped with empty notes because their specs
had no doc string at all (the "no doc list?" stubs): every block
field, the base64_decode encodings, the json_ref return types, and
the vrf_verify standard. Add a doc field to each spec so the
generated NOTES columns are populated.

Also correct VotePK and SelectionPK, which were described as
"32 byte address": they are a participation public key and a VRF
public key. And fix two copy-paste comments that said VrfStandards
and BlockFields describe the json_ref immediate.

gitxn's field immediate carried the full TxnFields group even
though array fields fail at runtime (fetchField rejects them when
no index is supplied). txn, gtxn, gtxns, and itxn all use
TxnScalarFields for the same reason.

FieldGroup.SpecByName respects the sparse names array, so
"gitxn 0 Accounts" now fails at assembly with a helpful error
instead of assembling into bytecode that always fails at runtime.
Disassembly of such (always-invalid) bytecode now errors, matching
the other txn opcodes.

In the generated docs, gitxn's field immediate now references the
same "txn Fields" table the other txn opcodes point at.

v13 branches (bnz, bz, b, callsub) encode their offset as a
binary.Varint, but their OpSpecs reused immLabel, the two-byte
big-endian kind. That forced the disassembler to consult
spec.Version to pick a decoder, and the generated docs described
the v13 branch immediate as "int16 (big-endian)".

Give the varint encoding its own immediate kind, immVarintLabel,
so the encoding is a property of the immediate itself, and key
disassembly on the kind rather than the version. switch and match
keep two-byte offsets at every version, so immLabels is unchanged.

Only regenerated v13 docs change: the branch immediates now read
"varint (zigzag)".

Co-Authored-By: John Jannotti <jannotti@gmail.com>

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>