Docs content refinement pass (follow-up to #460)

[goodboy]

Motivation

PR #460 stood up the new docs site (pydata theme, d2 diagrams,
tested examples) as a scaffold + middle ground — the structure,
wiring, and current-API correctness are in, but substantial prose
still needs filling / refining across the guides. This issue tracks
that content pass so #460 can land immediately as the scaffold.

Scope

Refine + flesh out the written content across the docs tree
(docs/). Fill in per-page bullet notes as the refinement passes
happen:

• (TODO @goodboy — bullet notes per page/guide)

  • update the caps-based-msging section
    to include Type annotating Context.open_stream() (probably with msgspec.Struct subtype(s)) 😎 #365 which is the primary most recent issue which
    protos out our longer term type-annot-driven pld_spec API.

    • also point to our current test suites which i'm pretty
      already demo a higher-level approach then using tractor.msg._ops.limit_plds()?

    • also link in the new enc/dec_hook() factor PR enc_hook & dec_hook factory (+ CI uv update) #376 (from
      @guilledk) as the (potential) longer term refined public API.

      • it's a draft from the https://github.com/goodboy/tractor/tree/auto_codecs branch
        (which needs a serious rebase!)

  • adding (at least tractor.*) typing to all examples/
    scripts scripts like the front page
    one

  • adjustments for when we move Portal.run_in_actor() into
    a tractor.hilevel/api or wtv.

  • proper Registrar-as-subsys (not the root actor) example set
    (ideally with multiple proto backends per ).

  • a whole detailed guide section on the SCSP (SC supervision
    protocol) per tHe GoD uNpRoToCoL #297
    and extending the dgram @ https://goodboy.github.io/tractor/guide/context.html#the-context-a-cross-actor-task-pair

  • add more complex scenarios such as requested loong ago
    😂 Deployment Scenarios and Testing #97

    • compare and contrast examples from competitor projects per,
      Recipe for "actor class" style stuff like ray and pykka #191
    • how-to scale a py web framework per,
      Add a "farming" example. #238
    • real-world complex use case of infected-aio mode per,
      Document an "infected asyncio" sub-actor tutorial #180
    • show how to build a "micro celery" all in tractor per,
      Impress the celery crowd #83
    • take one (or more?) of the above and show how to use the
      debug_mode=True feats in an actual complex distributed sys
      per, The debugger readme example is deprecated #270
    • a proper dining philosophers example!

• actually post about the project, likely on the trio discourse
  forum per,
  Pump eet? #2

Known thread to fold in here:

• Sweep the guide pages for any run_in_actor()-led showcase
  examples and reframe where the Context API should lead (e.g. the
  inlined snippets in guide/rpc.rst + guide/spawning.rst and
  their backing scripts). NB most existing refs already correctly
  cast run_in_actor() as the convenience wrapper atop the core
  Portal.open_context() model — keep those; this is the
  headline-example pass, not a blanket purge.

Notes

• Infra/scaffold (theme, d2 pipeline, gh-pages deploy, tested
  examples) is done in Docs (vibed) for serious: real documentation with a modern theme  #460; this issue is purely content.
• Related open docs-labelled issues:
  https://github.com/goodboy/tractor/issues?q=is%3Aissue+state%3Aopen+label%3Adocs

(this issue was generated in some part by claude-code)