fix: resolve the eight-item review audit (13 issues, 2 breaking changes)

[baraline]

Resolves an eight-item review of the package by verifying each claim against the code
before acting on it. Every one turned out partly founded — none was fully correct as
written, and none was baseless. Two of the proposed remedies would have broken the
package.

Closes#22, #23, #24, #25, #26, #27, #28, #29, #30, #31, #32, #33, #34.
Leaves #35 open pending a decision.

Every change was test-first: a failing test, verified failing for the right reason, then
the fix. 1084 passing (was 941), 97.26% coverage, mypy strict clean, codegen in sync,
zero-warning docs build.

---

⚠️ Two breaking changes

1. server_timezone is now a required client argument (GLPI_SERVER_TIMEZONE for
from_env), taking an IANA name or a tzinfo.

There is deliberately no default. Against a Europe/Paris instance, assuming UTC shifts the
affected timestamps by two hours and stops them raising — a loud failure becomes a quiet
wrong answer. A name rather than a fixed offset because a name follows DST; the same
instance emits both +01:00 and +02:00. Adds tzdata on Windows, which ships no system
tz database.

It governs both directions. On read it interprets the timestamps GLPI sends bare; on
write it converts an aware datetime onto the server's clock, because GLPI discards the
offset it is sent — see the measurement below.

2. Search endpoints raise GlpiStatusError on a 4xx instead of returning [].

This reverses decision D2 of the 0.4.0 error work, which chose tolerance deliberately.
Callers relying on [] after a permission error must now catch GlpiStatusError.

---

Bugs fixed

#	Defect
#22	Every datetime write raised TypeError.model_to_payload dumped in python mode, leaving live datetime objects for json.dumps. Invisible to the suite because TransportRecorder stubs above the JSON encoder — the new test asserts encodability, not shape.
#23	get_ticket_statistics silently truncated at 200 tickets on an instance whose own docstring records 59,690. One call, no loop. The two entity and one user name-resolution sites had the same shape.
#24	Fenced code blocks degraded to inline <code>, tables to literal pipes, and snake_case accumulated backslashes on every read.
#25	_MAX_DATETIME was naive, so to_markdown() raised on mixed-awareness timelines. Reachable with no code change — and the live probe later confirmed the mixed population is real.
#26	require_response_int refused numeric-string ids, data-nested ids and Location-header creates, raising a protocol error over a usable identifier.
#27	from_transport silently deleted text."use the <Enter> key" → "use the key". Now decided by HTML element name.
#28	A 403 made a batch iterator end having yielded nothing, so the caller saw a successful empty walk.
—	sort="date_mod desc" — the library's own documented example — is HTTP 400. Found while running the probe. Correct syntax is field:direction; bare date_mod is accepted but sorts ascending, and order= is ignored.
—	GLPI discards the offset on every datetime write. Measured: 12:30:00 bare, as ...Z, and with +02:00/+09:00/-08:00/+14:00 all store 12:30 Paris. 12:30-08:00 is 21:30 there, so that write lands nine hours early with a 200. Aware values are now converted before sending.
—	Three construction examples had server_timezone inserted twice. A repeated keyword is a SyntaxError, so they could not be copied at all. Plus two older doc defects: stranded output inside a code-block:: python, and an import indented four spaces in a three-space block.

Features

• stream_document_content — yields a document body in chunks instead of buffering it whole (Add streaming document download (stream_document_content) #30).
• Four missing batch iterators — KB articles, KB categories, documents, locations (Add iter_search_* for KB articles, KB categories, documents and locations #29).
• glpi_python_client.rsql — public created_between / date_window / changed_since, deduplicating three hand-built windows (Add a public RSQL date-window builder (retargeted to date_creation) #34).
• find_user_by_email — a deterministic scan, because GLPI exposes addresses as a nested array the v2 filter engine cannot join (Add find_user_by_email with a deterministic implementation #33).
• Round-trip corpus — 21 cases, four known losses as xfail(strict=True) so fixing one fails the suite rather than drifting (Decide the nl2br trade-off and land a round-trip corpus test #32).

---

Three findings worth reading

The obvious fix for #27 would have broken the package.from_transport is wired as a
Pydantic BeforeValidator, so it also runs on caller-authored Markdown on the way out.
Deleting the guard escapes **bold** into literal asterisks. Measured: 938 passing → 9
failing, on both the bare deletion and the proposed _looks_like_html() probe — which is
additionally a no-op on both reported symptoms.

#31's premise was largely false, and measuring said so. Rather than build the proposed
machinery, a live probe found 19 of 20 datetime fields already arrive aware. The one
straggler (KBArticle.revisions[].date) genuinely breaks — comparing it with its own
parent article raises — so the fix shipped, but scoped to what the data justified.

#35's cheap option was ruled out by measurement. The POST body is {"id", "href"}, so
obtaining a created record is a real second round trip. Had it returned the full record,
the fix would have been "stop discarding it" — no new API.

integration_tests/probe_wire_format.py is included so these are reproducible.

---

Reviewer notes

• All nine skills and both guides are reconciled with this branch. Every client
  construction example — 7 across the skills, 5 across docs/user_guide.rst and
  README.md — gained the now-required server_timezone; as written they would all have
  raised TypeError. The five skills that documented the 4xx-swallowing contract at length
  now say what happens instead, while keeping the warning about the fail-open path that has
  not changed. The knowledge-base skill also carried sort="date_mod desc" — the same
  HTTP 400 the docstrings had.
• test_every_public_method_is_named_by_some_skill caught stream_document_content
  after rebasing, and was right to. Worth knowing it exists: adding a public method without
  naming it in a SKILL.md fails the suite, and _UNDOCUMENTED is deliberately empty.
• The offset-on-write question is now measured, and the answer was the dangerous one.
  GLPI accepts an offset and then ignores it — seven spellings of one moment, from -08:00
  to +14:00, all stored the same wall clock. It is not skipping the parse either: +99:99
  answers HTTP 500. So server_timezone did gain a second job, and mode="json" alone
  would have shipped writes that are silently wrong by up to twelve hours. Probe 3 in
  integration_tests/probe_wire_format.py reproduces it.
• Two new structural guards, both verified by breaking them: no library module may call
  model_to_payload without the timezone, and all 77 documented Python snippets must
  compile. The second uses compile rather than ast.parse because ast.parse accepts a
  repeated keyword argument — parsing alone would have passed the file it was written to
  catch.

🤖 Generated with Claude Code

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 97.33333% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.24%. Comparing base (713c540) to head (997b0c3).

Files with missing lines	Patch %	Lines
glpi_python_client/models/_base.py	92.59%	2 Missing ⚠️
...pi_python_client/_async/clients/commons/_config.py	93.75%	1 Missing ⚠️
glpi_python_client/_async/clients/commons/_http.py	96.42%	1 Missing ⚠️
...python_client/_async/clients/commons/_transport.py	95.83%	1 Missing ⚠️
glpi_python_client/rsql.py	96.55%	1 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@ Coverage Diff @@## main #36 +/- ##
==========================================
+ Coverage 97.10% 97.24% +0.13% 
==========================================
Files 79 80 +1 Lines 2422 2609 +187 ==========================================
+ Hits 2352 2537 +185 - Misses 70 72 +2 

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.