Document query edge cases and exit-status meanings

[memotype]

Severity: Low
Expected real-world likelihood: Medium for caller confusion; low direct failure impact

Problem

The README documents status 1 for a missing key/index, but it does not provide a complete exit-status contract or define several query edge cases.

Current behavior and recent issue decisions expose distinctions callers may need:

• status 0: selected value, including an empty string;
• status 1: missing key/index;
• status 2: malformed/unsupported input, including an empty query term;
• array indexes are matched as exact decimal strings, so 1 works while spellings such as 01 or +1 do not;
• duplicate nonempty object member names select the first encountered direct member in ordinary cases;
• escaped and decoded-equivalent key spellings are intentionally distinct, which is already documented separately.

The parser bugs tracked in other issues currently cause additional status inconsistencies. This documentation should describe the intended contract after those decisions are resolved, not legitimize accidental behavior.

Reproduction examples

./bj.sh '{"value":""}' value      # status 0, empty output
./bj.sh '{"value":""}' absent     # status 1, empty output
./bj.sh '{"value":1}' ''          # status 2, empty output

./bj.sh '[10,20]' 1               # 20, status 0
./bj.sh '[10,20]' 01              # empty, status 1

./bj.sh '{"a":1,"a":2}' a         # currently 1

Possible fixes (suggestions only)

This issue is primarily about choosing and documenting contracts:

• Add a concise exit-status section to the README.
• Define accepted array-index spelling.
• State the duplicate-name policy or explicitly declare duplicate names unsupported/undefined.
• Keep invalid-JSON behavior outside the validator scope.

These are possible documentation directions, not prescribed parser changes.

Suggested coverage

After each contract is confirmed, add compact regression cases for status distinctions, index spelling, and duplicate-name handling so documentation and behavior remain aligned.