docs: rewrite platform docs as the shipped-venue source of truth

[mfw78]

What

Rewrites docs/05-sdk-design.md and docs/08-platform-generalisation.md (plus one link fix in docs/sdk.md) to match the shipped M1-M3 architecture: the venue persona (videre-sdk, #[videre_sdk::venue]/#[videre_sdk::keeper]) is documented as shipped, venue adapter components are named as the sole domain-extension mechanism, and shepherd:cow/cow-api is reframed as the retired legacy read path (cow-events ABI package of record only).

docs/sdk.md is corrected alongside them: it still titled itself "nexum-sdk + shepherd-sdk", documented a CowApiHost row against the deleted shepherd:cow/cow-api, named the removed bind_cow_host_via_wit_bindgen! macro and classify_api_error, and linked into crates/shepherd-sdk-test/. It now describes the videre-sdk venue seam, the client capability, and the nexum-sdk-test plus videre-test companions.

Why

The prior docs were actively misleading post-M1-M3: doc 05 described the venue persona as unshipped design intent when it ships, and doc 08 still documented the deprecated Layer-3 host-extension model as the live mechanism.

Testing

Docs-only change; no code touched. Prose reviewed against the M3 tip crate layout (nexum-sdk, videre-sdk, videre-macros, videre-test, cow-venue, composable-cow).

AI Assistance

Drafted with AI assistance under human review.

Closes #401

[lgahdl]

Clean. Verified against the actual PR head: every mention of retired crate names (shepherd-sdk, shepherd-sdk-test, shepherd-cow-host) is on a removed line, no leftover reference on an added line, and no pre-rename names (nexum-venue-sdk/nexum-venue-test) survive anywhere. The #[videre_sdk::venue]/#[videre_sdk::keeper] macro descriptions match the real macro doc comments exactly. The egress-guard framing is careful and accurate — it correctly says "advisory," not overclaiming enforcement that isn't there. Approving.

[mfw78]

Thanks. One thing your check could not have caught, because it is diff-scoped rather than file-scoped, and it is now fixed in this car.

Your invariant was that every mention of a retired crate name sits on a removed line with none on an added line. That held, but only because docs/sdk.md's stale content was neither added nor removed by this diff: it sat in context. The file itself still described a world deleted three cars ago.

Concretely, at the pre-ripple head it was titled "The module SDK: nexum-sdk + shepherd-sdk", carried a CowApiHost capability row against the deleted shepherd:cow/cow-api@0.1.0, gave a cargo doc -p shepherd-sdk ... command that no longer resolves, named the removed bind_cow_host_via_wit_bindgen! macro and cow::error::classify_api_error, and linked readers into ../crates/shepherd-sdk-test/src/lib.rs. Eleven references in total, inherited from #471's cone deletion rather than introduced here.

Since this car's whole charter is that the docs are the shipped source of truth, leaving the SDK entry page in that state would have made the claim false. It now describes the videre-sdk venue seam (VenueClient over VenueTransport, IntentBody, retry_action), the client capability rather than cow-api, and the real companions.

Each replacement was checked against the tree rather than inferred: the crates exist, gpv2_to_order_data is in cow_venue::assembly, Verdict and LegacyRevertAdapter are in composable-cow, MockFetch is in videre-test::transport, MockHost is in nexum-sdk-test, and "client" is the literal capability constant in videre-macros/src/keeper.rs. I deliberately did not describe videre-test as a shepherd-sdk-test replacement, since it is a venue conformance kit with transport mocks rather than a composed MockHost.

Also deduplicated Closes #401, which appeared twice in the body.

For the record on the ripple itself: this car arrived with cow-orderbook-only and rustdoc red on its pre-ripple head, both inherited from #473. Both clear against the current base, since the layering-gate fix landed with #473.