docs(sdk): rewrite doc 05 around the two-persona SDK plan

[mfw78]

What

Rewrites docs/05-sdk-design.md end to end around the two-persona SDK plan from issue #224.

• Documents the module-author persona as actually shipped: crate layout for nexum-sdk and shepherd-sdk, the host-trait seam (ChainHost / LocalStoreHost / LoggingHost plus the supertrait Host), and the bind_host_via_wit_bindgen! adapter.
• Documents the single #[nexum::module] attribute macro shipped by nexum-macros, verified against crates/nexum-macros/src/lib.rs and the modules/examples/http-probe port.
• Corrects two things the old aspirational doc got wrong: there is one macro, not a #[nexum::module]/#[shepherd::module] pair, and it always targets the blanket shepherd:cow world today.
• Corrects the old doc's async assumption: handlers are synchronous, with no async/block_on/&RootProvider injection.
• Documents the nexum-sdk-test/shepherd-sdk-test MockHost testing story as it actually exists.
• Introduces the venue-adapter persona as planned but not shipped, marked clearly as design intent tracked by a separate epic.

Why

The old doc described the 0.3+ north-star vision (macro-driven, async, two-macro split) rather than what shipped, so it misled module authors into writing against an API surface that does not exist. The rewrite realigns the doc with the shipped host-trait seam from ADR-0009 and the code under crates/nexum-sdk/, crates/shepherd-sdk/, and crates/nexum-macros/.

Testing

Docs-only change: a single file, docs/05-sdk-design.md (+267 / -956). No .rs, .wit, crate, module, or WIT-package files are touched.

• Confirmed the diff is docs-only (one Markdown file); no code or config surface to compile or exercise.
• cargo fmt --all -- --check (not applicable, no code touched)
• cargo clippy --workspace --all-targets -- -D warnings (not applicable, no code touched)
• cargo test --workspace (not applicable, no code touched)

AI Assistance

Claude (Opus) used for the docs rewrite.

Closes #224

[lgahdl]

Solid rewrite — removing the aspirational table and marking the venue-adapter persona clearly as unshipped is the right call. All six factual claims verified against the code. Three doc accuracy/completeness items inline.

[lgahdl]

The prose here and throughout the doc uses `#[nexum::module]`, but the actual attribute a module author writes is `#[nexum_sdk::module]` — the macro is re-exported at nexum_sdk::module, not under a nexum crate path. The code example a few lines below correctly writes #[nexum_sdk::module], so a careful reader notices the conflict; a reader who skims the prose will write #[nexum::module] and get an unresolved-macro error.

Suggestion: use `#[nexum_sdk::module]` everywhere in prose, and update this section header to ### The `#[nexum_sdk::module]` attribute.

[lgahdl]

CowApiHost is introduced with only submit_order named in the parenthetical. The trait also has cow_api_request — the REST passthrough for everything else: quotes, order-status, get-order, raw endpoints. A CoW module author who needs a quote (the common case for conditional orders) will look for a typed Cow client (which was described in the old doc; now deferred) and not find it, without realising cow_api_request is the raw fallback available today.

Suggestion: name both methods and add one line: `CowApiHost` (`submit_order` for order placement; `cow_api_request(method, path, body)` for the REST passthrough — quotes, order status, raw endpoints).

[lgahdl]

The note that handlers are synchronous appears after the code example. Readers who follow the prose example will have already attached async fn expectations — the old doc had extensive async fn on_block(block, &RootProvider) examples and many Rust frameworks use this shape. Moving the "Two things worth being precise about" block to before the code example (or adding a one-line callout at the top of the section) catches the async assumption before it lands.

[lgahdl]

One sentence for the chassis is thin for the primary abstraction used by TWAP-monitor, stop-loss, and any conditional-order module. Module authors targeting these flows land on WatchSet / Gates / Journal / ConditionalSource immediately, with none of the key invariants described here:

• WatchSet key format (watch:{owner}:{hash} in the local store)
• Gates semantics (TryOnBlock / TryAtEpoch gate poll timing)
• Journal for idempotent submission (submitted: prefix)
• ConditionalSource — the trait a module must implement

The //! doc block at crates/nexum-sdk/src/chassis.rs has a worked example covering all of this. Even a link or a three-line excerpt would save a conditional-order author from reverse-engineering the key convention from the TWAP monitor.