docs: record the repo gotchas a fresh session keeps rediscovering

[tas50]

Adds the context a full defect audit of this package turned out to need, and that nothing in the code or git history conveys.

The main addition: where the test doubles lie

A new "What the test doubles do not cover" section. Both suites go green on wire shapes a real Chef Server would reject or shape differently, and every gap listed there actually concealed a bug found in this audit:

• cinc-zero returns only all_files on a cookbook GET → hid the manifest duplication (fix: deduplicate cookbook manifest files by path #46)
• cinc-zero accepts run_list: null → hid the nil-slice encoding (fix: encode an empty run list as [] rather than null #50)
• cinc-zero populates a group's courtesy name field → hid the Groups.Update dependency on it (fix: fall back to GroupName in Groups.Update #48)
• cinctest replays whatever the fixture author wrote, so a wrong assumption about a response confirms itself forever

Plus the throwaway-probe technique that pinned these down, since "write a zz_probe_test.go, log what the client sends vs. what the server receives, delete it" is not obvious from the repo.

The rest

Section	Added
Adding a new service	esc() every caller-supplied identifier; a create returns (*Response, error) when the server answers with {"uri":…}
Auth and transport	the signed path must equal r.URL.EscapedPath(), not r.URL.Path (which is decoded and hides a mismatch), and verifySignature exists to check it; only transportErr-marked failures retry
Encoding edge cases	the nil-slice rule extends past groups to run_list and normal.tags; a Go type assertion matches the dynamic type exactly, so a bare map[string]any assertion misses Attributes
Linting (new)	the golangci-lint invocation that gives signal here, why gosec is mostly noise, and that a bare staticcheck binary fails on a Go-version mismatch

Dependency on the sibling PRs

Some lines describe code that lands with #44 (esc), #45 (asAttributeMap), #50 (MarshalJSON), #51 (Create signature) and #52 (transportErr). Merge this last, and if any of those is dropped, drop its line here — I've kept each to a single bullet so that's a one-line edit.

Test plan

• Documentation only — no code, no test changes
• Reviewed against the existing structure; additions slot into the sections that already exist rather than duplicating them
• Every claim was observed in this session, not inferred