Record PR #512 prompt provenance

Capture the human direction, generated changes, review findings and
validation results for the docs-example landing pass.

Point generated-code references at the complete commit range from
the pre-remediation branch head.

Prompt-IO: ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.md

(this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))

ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.md

@@ -0,0 +1,62 @@
+---
+model: openai/gpt-5.6-sol
+service: opencode
+session: pr512-docs-review
+timestamp: 2026-08-28T20:08:22Z
+git_ref: wkt/big_boi_docs_472_follow_ups
+scope: code
+substantive: true
+raw_file: 20260828T200822Z_0be872ff_prompt_io.raw.md
+---
+
+## Prompt
+
+Prime PR #512 for landing by applying the repository Python style and
+typing policy across changed examples, reviewing and correcting the
+result with delegated agents, validating it, and auditing documentation
+changes since PR #460 for broader follow-up work.
+
+## Response summary
+
+Completed a branch-wide style, typing, and docstring pass over the
+changed examples. Reworked the dedicated registrar example so it proves
+external discovery, handles bind collisions, publishes readiness
+atomically, and shuts down cleanly across platforms. Staged review moved
+it under the discovery examples, introduced an async lifecycle manager,
+and captured public-subsystem, Piker, and pytest follow-ups. Corrected
+discovery and typed-messaging documentation after cross-checking runtime
+behavior.
+Created issue #514 for typed `Start` contracts and linked its planned
+sender-side argument validation from the messaging guide.
+Independent review passes were repeated until no actionable findings
+remained. Static checks, Sphinx, runnable examples, Trio coverage, and
+focused registrar checks passed; Ctrl-C debugger failures remain
+unclassified after one case reproduced on untouched `main`.
+
+## Files changed
+
+- `examples/discovery/dedicated_registrar.py` - implement robust
+  standalone registrar discovery and teardown.
+- `examples/**/*.py` - apply style, typing, docstring, and terminology
+  corrections to the 38 changed example modules.
+- `docs/guide/discovery.rst` - document actual registrar and
+  multi-registrar behavior.
+- `docs/guide/msging.rst` - document actual validation and codec-hook
+  boundaries.
+
+## Human edits
+
+The human selected PR #512, required the `/py-codestyle` policy and
+typing improvements throughout the examples, required delegated review
+agents to find additional fixes, authorized agents to own and push their
+code through the proper review process, and requested a broad audit of
+documentation changes since PR #460 rendered as an evolving Taken WIP.
+The human then required the earlier `ParamSpec` proposal to be captured
+as a dedicated GitHub issue and linked from the current docs patch.
+The human also required the registrar demo to move under discovery, use
+structural matching and an async context manager, explain socket ownership,
+and preserve public API, Piker, and pytest-harness follow-ups.
+The human also explicitly retracted messages intended for another
+session; those messages did not direct the result. No direct manual
+source edits were identified; the agent applied the human-directed
+changes.

ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.raw.md

@@ -0,0 +1,90 @@
+---
+model: openai/gpt-5.6-sol
+service: opencode
+timestamp: 2026-08-28T20:08:22Z
+git_ref: wkt/big_boi_docs_472_follow_ups
+diff_cmd: git diff 0be872ff..HEAD
+---
+
+## Prompt
+
+Prime PR #512 for landing. Apply the Python style policy throughout
+the changed examples, improve typing, use review agents to find and
+fix correctness issues, run the proper review process, push the agent's
+own code, and then audit documentation changes since PR #460 for stale,
+missing, defunct, or improvable coverage.
+
+## Response
+
+> `git diff 0be872ff..HEAD -- examples/`
+
+Restyled and typed all 38 changed example modules while preserving
+intentional debugger failures and hanging reproducers. Added required
+multiline docstrings, corrected async callable annotations, modernized
+legacy API terminology, and preserved complete debugger process trees.
+
+Rebuilt `examples/discovery/dedicated_registrar.py` as a real
+external-discovery example. A standalone registrar process now selects
+and retries bounded ephemeral addresses, publishes readiness atomically,
+rejects accidental registrar reuse, serves sibling service and client
+actors, proves lookup used the registrar instead of a local-peer channel,
+and performs bounded, validated, cross-platform shutdown.
+
+Staged review moved the demo into the discovery example group, converted
+collision classification to structural pattern matching, documented the
+selector-socket close/rebind race, and extracted process ownership into an
+async context manager. A source TODO records the future public discovery
+subsystem, Piker service-management lessons, and pytest registry-isolation
+use case.
+
+> `git diff 0be872ff..HEAD -- docs/guide/discovery.rst`
+
+Corrected registrar, duplicate-name, and multi-registrar discovery
+guidance, including configured-order and `None` placeholder behavior.
+
+> `git diff 0be872ff..HEAD -- docs/guide/msging.rst`
+
+Corrected typed-payload validation boundaries and separated working
+task-scoped codec encoding from private per-dialog decoding and the
+incomplete decorator hook parameters.
+
+## Review and validation
+
+Multiple independent reviews found and drove fixes for registrar
+discovery validity, port-selection races, teardown, process diagnostics,
+shutdown status, inaccurate discovery ordering, async callable typing,
+missing docstrings, truncated debugger command diagrams, stale APIs, and
+payload-error relay wording.
+
+Validation completed:
+
+- AST parsing, Ruff, 69-column checks, and required-docstring audit for
+  all 38 changed Python files.
+- Sphinx HTML build succeeded.
+- Documentation example harness: 24 passed.
+- Trio coverage: 7 passed, 4 xfailed, 1 xpassed.
+- Dedicated registrar direct run and focused harness test passed with a
+  clean child exit and no traceback.
+- Debugger suite: 20 passed, 6 skipped, and 8 reproducible
+  `ctl-c=True` pexpect timeouts. One exact failure reproduced on
+  untouched `main`, confirming a baseline failure; its root cause
+  remains unclassified. No leaked actor processes remained.
+
+The post-PR-#460 audit identified follow-up work around advertised but
+inert runtime selectors, platform/backend support, unresolved discovery
+contracts, cached-context teardown, codec recipes, examples-as-tests
+coverage, public API exports, broadcast factory contracts, stale examples,
+README duplication, release notes, and process-title terminology.
+
+## Follow-up prompt
+
+Capture the previously proposed `ParamSpec`-based `Start` argument
+validation work in a focused GitHub issue, then link it from the current
+typed-messaging docs patch as planned sender-side checking.
+
+## Follow-up response
+
+Created https://github.com/goodboy/tractor/issues/514 to track deriving
+typed `Start` contracts from endpoint signatures, preserving caller-facing
+signatures, and validating arguments before sending where possible. Added
+the issue link beside the guide's current `Start` validation boundary.