Docs (vibed) for serious: real documentation with a modern theme

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: docs
+
+# build sphinx docs on every PR + push to main;
+# deploy to gh-pages only from main pushes.
+# (see goodboy/tractor#123 for the original ask)
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  # to run workflow manually from the "Actions" tab
+  workflow_dispatch:
+
+# needed by actions/deploy-pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# never run >1 pages deploy at once
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: 'sphinx build'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install latest uv
+        uses: astral-sh/setup-uv@v6
+
+      # NOTE, no `d2` bin is installed in CI (yet) so
+      # the pre-rendered + committed SVGs under
+      # `docs/_diagrams/` are used as-is; see
+      # `docs/_ext/d2diagrams.py` for the fallback
+      # policy.
+      - name: Build html docs
+        run: |
+          uv sync --no-dev --group docs
+          uv run --no-dev --group docs make -C docs html
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    name: 'deploy to gh-pages'
+    if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

ai/prompt-io/claude/20260611T175152Z_8526985c_prompt_io.md

@@ -0,0 +1,93 @@
+---
+model: claude-fable-5[1m]
+service: claude
+session: 0780a862-e19a-4f0a-86cd-c8afc0997757
+timestamp: 2026-06-11T17:51:52Z
+git_ref: 8526985c
+scope: docs+code+config
+substantive: true
+raw_file: 20260611T175152Z_8526985c_prompt_io.raw.md
+---
+
+## Prompt
+
+> we need big boi docs; ours are way out of date and generally
+> terrible. i'd like to use a sphinx theme in the vein and/or
+> one-of/nearly-the-same-as used in one or all of the `msgspec`,
+> `numpy`, `ray`, `xonsh`, `polars` projects.
+>
+> see the following oustanding but now very old issues to guide
+> you: #175, #126, #123, #157
+>
+> we should try to target a 3 columned sphinx theme with,
+> - document index-nav on left,
+> - body content in middle,
+> - diagrams (ideally in d2lang if possible) on RHS
+>
+> optimize for (if possible),
+> - reusing examples code without duplication in docs,
+> - generating new examples from todos throughout code base,
+> - distilling the essence of SC across processes in the simplest
+>   and most friendly way possible.
+>
+> do this work in a /open-wkt and do you best without my guidance
+> for the first major pass - we will refine asap once you are
+> complete.
+
+Session settings: `/effort max` + ultracode (multi-agent workflow
+orchestration). Fully autonomous first pass; two orchestrated
+agent fleets were used (6-agent recon survey, then 10-agent
+content fan-out: 9 section writers + 1 examples smith), with the
+orchestrator authoring the landing page, SC essay, sphinx
+scaffold, d2 pipeline + diagram sources, CI workflow and all
+integration/fix passes directly.
+
+## Response summary
+
+Complete sphinx docs revamp on branch `wkt/big_boi_docs`:
+`pydata-sphinx-theme` 0.18 (3-column: left nav / content /
+page-toc, with d2 diagrams + asides floated into the RHS margin
+via custom CSS), sphinx 9.1, a local `.. d2::` directive
+rendering `docs/diagrams/*.d2` sources with committed-SVG
+fallback, a vendored `.. margin::` directive, ~25 new doc pages
+(landing, start/, explain/, 12 guides, 10 api-ref pages,
+project/), 5 new auto-tested examples + 3 modernized + 1
+renamed, and a gh-pages deploy workflow (issue #123). All
+example code is `literalinclude`d from `examples/` (zero
+duplication, CI-verified). Build: green, 24 warnings all
+pre-existing-docstring/NEWS sourced.
+
+## Files changed
+
+See the branch diff (uncommitted at entry-write time):
+
+> `git diff test_cpu_throttling..wkt/big_boi_docs`
+> `git -C <wkt> status --short` (pre-commit working tree)
+
+- `docs/conf.py` — full rewrite for pydata theme + ext stack
+- `docs/_ext/d2diagrams.py` — new `.. d2::` sphinx directive
+- `docs/_ext/marginalia.py` — new `.. margin::` directive
+- `docs/_static/css/custom.css` — b&w skin + RHS margin floats
+- `docs/diagrams/*.d2` (7) — diagram sources (sketch/grayscale)
+- `docs/_diagrams/*.svg` (7) — committed rendered fallbacks
+- `docs/index.rst` — new landing (replaces dead-API doc)
+- `docs/start/*.rst` (3), `docs/explain/*.rst` (3),
+  `docs/guide/*.rst` (13), `docs/api/*.rst` (10),
+  `docs/project/*.rst` (3) — new content tree
+- `docs/dev_tips.rst` — removed (ported to project/dev-tips)
+- `examples/{typed_payloads,nested_actor_tree,
+  service_daemon_discovery,uds_transport_actor_tree,
+  streaming_broadcast_fanout}.py` — new, smoke-tested
+- `examples/{a_trynamic_first_scene,
+  actor_spawning_and_causality,parallelism/single_func}.py` —
+  `.result()` -> `.wait_for_result()` modernization
+- `examples/parallelism/concurrent_futures_primes.py` — renamed
+  from leading-underscore + trio-runner shim added
+- `pyproject.toml` — `docs` dependency-group filled in
+- `uv.lock` — relock for docs group
+- `.github/workflows/docs.yml` — build + gh-pages deploy
+
+## Human edits
+
+None yet — entry written pre-commit; the author reviews, stages
+and commits manually (per repo workflow policy).

ai/prompt-io/claude/20260611T175152Z_8526985c_prompt_io.raw.md

@@ -0,0 +1,49 @@
+---
+model: claude-fable-5[1m]
+service: claude
+timestamp: 2026-06-11T17:51:52Z
+git_ref: 8526985c
+diff_cmd: git diff test_cpu_throttling..wkt/big_boi_docs
+---
+
+# Raw output pointers (diff-ref mode)
+
+All generated content is code/config/docs committed alongside
+this entry on branch `wkt/big_boi_docs`; per the prompt-io
+diff-ref decision rule each file's verbatim content is the diff
+itself rather than a copy here:
+
+> `git diff test_cpu_throttling..wkt/big_boi_docs -- docs/`
+> `git diff test_cpu_throttling..wkt/big_boi_docs -- examples/`
+> `git diff test_cpu_throttling..wkt/big_boi_docs -- pyproject.toml uv.lock .github/`
+
+## Generation notes (non-code output summary)
+
+- Theme research (web, agent-verified 2026-06-11): msgspec=furo,
+  xonsh=furo, numpy/ray/polars=pydata-sphinx-theme (ray migrated
+  off sphinx-book-theme); sphinx-book-theme 1.2.0 hard-pins
+  pydata 0.16.1 (stale) -> chose pydata 0.18 + sphinx 9.1.
+- d2 ecosystem: no production-grade pypi extension exists
+  (sphinxcontrib-d2lang 0.0.5 ignores returncodes, uuid4 output
+  names; sphinx-d2 is an empty stub) -> wrote local
+  `docs/_ext/d2diagrams.py` (~230 LOC) with D2_BIN env
+  discovery, mtime caching, committed-SVG fallback and
+  literal-block last resort.
+- Diagrams authored in d2 (theme-id 1 "Neutral Grey" + sketch
+  mode + ELK layout, validated by render + headless-firefox
+  screenshot loop): actor_tree, context_handshake (real
+  msg-spec names Start/StartAck/Started/Yield/Stop/Return),
+  streaming_pipeline, runtime_stack, debug_lock,
+  error_propagation, infected_aio.
+- API truth enforced from a 6-agent recon pass over the
+  reorganized package tree (runtime/, discovery/, spawn/, ipc/,
+  msg/, devx/, trionics/): docs teach `.wait_for_result()`,
+  registrar (not arbiter) naming, `@tractor.context` +
+  `open_context()` as the core model, `run_in_actor()` as
+  convenience only.
+- All ~30 literalincluded example scripts verified present; 9
+  touched/new example files smoke-run green (exit 0, <16s).
+- Final build: `sphinx-build -b html` succeeded; 24 residual
+  warnings, every one sourced from pre-existing library
+  docstring rst-isms or legacy NEWS.rst content (left untouched
+  by design; flagged for a follow-up docstring lint pass).