docs: adopt a documentation style guide and bring the docs into compliance

Corosio's documentation had no stated standard and no way to check one. This
adds both, and applies them.

**The standard.** `doc/STYLE_GUIDE.md` defines five axes -- Structure,
Accuracy, Wording, Completeness, Presentation -- over the Diátaxis modes,
a single-source-of-truth rule for code and signatures, a controlled
vocabulary, and the enforcement tiers that say which rules block a merge.

**The machinery.** `doc/lint/` holds nine checks: structural AsciiDoc and nav
rules, sentence length over both corpora, docstring extraction so prose rules
reach the headers, tagged-include resolution, MrDocs reference warnings, a
self-test that mutates the linters and asserts they notice, and a gate that
compares a run against `baseline.json`. `doc/.vale/` adds the Corosio styles
and vocabulary. The Documentation workflow runs all of it, with the
structural and sentence-length rules blocking and the reference surface
reporting.

**The compliance work.** Every page declares its Diátaxis mode; listing
blocks are tagged and sourced from compiled snippets rather than pasted;
prose links the reference through `cpp:` macros instead of restating
signatures; tense, fluff, and terminology follow the guide. The reference
side documents every parameter, return value, and backend trait the
generator asked for, and MrDocs now builds the public headers with warnings
enabled and reports none.

**One API change.** The awaitables returned by the I/O initiators were plain
structs whose captured arguments, out-parameters, constructor, and CRTP
dispatch hook were all public, committing the library to a surface it never
intended to offer. Only `await_ready`, `await_suspend`, and `await_resume`
are the interface, and the compiler is what calls those; everything else is
private now. Member-initialisation order is unchanged.

**Repairs the audit turned up.** `message_flags::dont_route` does not exist
and five docstrings cited it; `native_tcp`/`native_udp` claimed `family()`
was a compile-time constant when only `type()` and `protocol()` are;
`local_stream.hpp` referenced a symbol that exists nowhere, which MrDocs
renders as nothing rather than a broken link; `io_context.hpp` pointed at a
`post()` overload that no longer exists; `shutdown_type` omitted
`udp_socket` from the types that use it; `4a.tcp-networking.adoc` re-taught
TCP internals the networking tutorial owns and now cross-links them.

**Cancellation and message-flag claims.** The cancellation wording
`289c5d2c` introduced generalises too far. `decode_io_result` lets a decided
result outrank the cancellation flag only when `bytes > 0`, so "an operation
whose result is already decided reports that result" holds for
byte-transferring operations and fails for zero-byte ones. Narrowed on
`tcp_acceptor::cancel`, its `implementation::cancel`, and `resolver::cancel`,
whose operations -- accept, wait, resolve -- never transfer a byte, so a
racing cancel always reports `operation_canceled`. Left as it was on
`tcp_socket`, `local_stream_socket`, `local_datagram_socket`, `udp_socket`
and `stream_file`, which do transfer bytes. `close()` in
`random_access_file.hpp` and `stream_file.hpp` still carried the
pre-`289c5d2c` unconditional claim although it tears down through the same
path `cancel()` uses; both now defer to `cancel`'s contract.

`udp_socket::implementation`'s four operations described `flags` as "Platform
message flags (e.g. `MSG_DONTWAIT`)". At that layer the parameter still
carries the portable `message_flags` bit pattern -- the public overloads
forward `static_cast<int>(flags)` unchanged and `to_native_msg_flags`
translates inside the backend -- and `MSG_DONTWAIT` is not in that mapping at
all, which maps only peek, out_of_band and do_not_route.

Also: `@return` added to four non-void functions that documented only
`@throws` (`random_access_file::size`, `stream_file::implementation::size`
and `::release`, `native_resolver::operator=`); `@tparam Ex` added to the
executor constructors of `local_stream_socket` and `local_datagram_socket`,
matching `tcp_socket`; and `basic_mocket::write_some`'s `@return` now states
the partial-write contract `7bc2fa76` introduced.

`doc/prompts/` carries the audit and repair tooling that found these, and
`doc/design/style-guide-compliance.md` records the adoption plan.

Author: mvandeberg

.github/workflows/docs.yml

@@ -1,2 +1,6 @@
 node_modules/
 build/
+lint/.docstrings/
+# Vale-managed style packages (regenerated by `vale sync`); Corosio/ is ours and is tracked.
+.vale/styles/Google/
+.vale/styles/Vale/

doc/.gitignore

@@ -0,0 +1,96 @@
+StylesPath = .vale/styles
+MinAlertLevel = warning
+; Pinned deliberately. A bare `Packages = Google` resolves to whatever release the
+; feed serves at `vale sync` time, so the corpus moves underneath baseline.json and
+; findings appear as NEW without a word of prose changing. Note the project also
+; moved errata-ai -> vale-cli. Bump this URL on purpose, and reseed in the same change.
+Packages = https://github.com/vale-cli/Google/releases/download/v0.7.1/Google.zip
+; Corosio domain vocabulary: .vale/styles/config/vocabularies/Corosio/accept.txt.
+; It holds genuine prose words and proper nouns ONLY. Bare C++ identifiers used as
+; running text stay unlisted on purpose — they are style-guide B1 defects and must
+; keep showing up as Vale.Spelling alerts until the prose is fixed.
+Vocab = Corosio
+[*.adoc]
+BasedOnStyles = Vale, Google, Corosio
+; NO BlockIgnores here, on purpose. Vale's native AsciiDoc handling (it shells out to
+; asciidoctor and only lints extracted prose nodes) already excludes delimited listing
+; blocks — `[source,cpp]`/`----`, bare `----`, `....` literal blocks, blocks nested in
+; list items or admonitions, `role=pseudocode`/`role=external`, and callout markers are
+; all skipped natively. A `BlockIgnores = (?s) *(\[source.*?----.*?----)` substitution
+; does NOT additionally protect anything — it destroys the `----` delimiters before
+; asciidoctor sees them, which corrupts the block structure and hands the code inside to
+; the linter as if it were a paragraph. That was measured on Capy's corpus, where
+; removing the line dropped `.adoc` warning-level alerts 503 -> 376; Corosio inherits the
+; decision rather than re-deriving it. If you are tempted to add a BlockIgnores line for
+; source blocks: don't. Confirm first, with an isolated fixture, that Vale is actually
+; failing to skip something.
+;
+; One Vale/asciidoctor artifact to know about before chasing a missing alert: a
+; correctly-excluded code block can suppress an UNRELATED, later Vale.Spelling or
+; Google.Colons alert when the block's own text shares a SUBSTRING with the flagged word,
+; and only when the block sits BEFORE the flagged prose in the file. Reduced fixture:
+; `// token` before a paragraph containing `foo_token` suppresses the alert; `// hello`
+; before it does not. This is a position-resolution artifact, not something any
+; BlockIgnores/TokenIgnores value controls — do not try to "fix" it with a config change
+; without a bite-tested fixture proving the change does something.
+;
+; Ignore inline code spans (backticks) AND `cpp:target[...]` reference macros: the B1
+; conversion replaces backtick symbol spans with cpp: macros, and their symbol text must
+; stay unlinted, exactly as the backtick spans were.
+;
+; The third clause is the fixed label of the boost-wide thread-safety idiom
+; ("Distinct objects: Safe." / "Shared objects: Unsafe."). Each instance is a genuine
+; Google.Colons hit, but the form is boost-wide and Corosio does not get to rewrite it;
+; `grep -ro '\(Distinct\|Shared\) objects:' --include='*.hpp' include` reports 72, spread
+; over io_context, resolver_results, endpoint, signal_set, tcp_acceptor, the TLS streams
+; and others. Only the LABEL and its colon are blanked, so whatever follows stays fully
+; linted by every other rule; the pattern deliberately does NOT spell out "Safe."/
+; "Unsafe." because instances continue into longer clauses that a phrase-exact form would
+; leave exposed while suppressing its siblings.
+; This is NOT a Google.Colons demotion, on purpose: demoting the rule would also hide the
+; genuine non-idiom Colons hits.
+TokenIgnores = (\x60[^\x60]+\x60), (cpp:[^\s\[]*\[[^\]]*\]), ((?:Distinct|Shared) objects:)
+
+; --- Google house-style pack: deliberately demoted, not abandoned ----------------
+; These eight rules encode GOOGLE's house style, not Corosio defects, and are scoped out
+; of the "vale clean" criterion. They are demoted to `suggestion` (below MinAlertLevel)
+; rather than removed, so a curious reader can still run
+; `vale --minAlertLevel=suggestion` and see them. Counts below are measured on Corosio's
+; two corpora at the port commit — `.adoc` = doc/modules, docstrings =
+; lint/.docstrings — and are the same ruling Capy made, re-measured here rather than
+; inherited.
+;
+; Google.Headings — Corosio writes Title Case section headings; Google style mandates
+;   sentence case. Retitling every heading is a user-visible house-style change, not a
+;   defect fix.
+; Google.WordListCase — Google's capitalisation list for words like "Internet"/"email";
+;   disagrees with Boost usage, not with Part C. Note Corosio's networking tutorial uses
+;   "Internet" heavily, so this rule is noisier here than in Capy.
+; Google.EmDash — bans spaced em dashes. Corosio uses ` -- ` (AsciiDoc's em-dash form) as
+;   a deliberate typographic convention.
+; Google.We / Google.FirstPerson — ban first-person. The tutorial and design prose
+;   address the reader directly by design (D1/D3).
+; Google.Latin — bans "e.g."/"i.e."; both are standard in Boost reference documentation.
+; Google.Quotes — demands commas and periods inside quotation marks (US convention).
+;   Corosio quotes code-like strings, where moving punctuation inside the quotes would
+;   misstate the string's contents.
+; Google.Spacing — flags spacing around punctuation in prose that is mostly quoted code.
+;
+; NOT demoted, on purpose: Google.Will (a genuine C4 signal, and C4 is gated),
+; Google.Colons, Google.OxfordComma, Google.LyHyphens, Google.Units, Google.Ordinal.
+;
+; Google.LyHyphens misfires on Corosio's `family-*` compounds -- `family-neutral`,
+; `family-sensitive`, `family-generic`, `family-specific`. The rule targets adverb
+; hyphenation (`newly-created`) and matches these only because "family" ends in "ly".
+; The hyphens are correct: they are compound adjectives, not adverbs. The rule stays
+; un-demoted because it catches the real thing elsewhere, so this bounded set of false
+; positives is carried in baseline.json instead -- grandfathered on purpose, not by
+; accident. Re-check it if the `family-*` vocabulary grows.
+Google.Headings = suggestion
+Google.WordListCase = suggestion
+Google.EmDash = suggestion
+Google.We = suggestion
+Google.FirstPerson = suggestion
+Google.Latin = suggestion
+Google.Quotes = suggestion
+Google.Spacing = suggestion

doc/.vale.ini

@@ -0,0 +1,14 @@
+extends: existence
+message: "Filler/fluff — delete or rewrite (style guide C5/C9): '%s'."
+level: warning
+ignorecase: true
+tokens:
+  - simply
+  - basically
+  - essentially
+  - obviously
+  - of course
+  - note that
+  - in order to
+  - due to the fact that
+  - utilize

doc/.vale/styles/Corosio/NoFluff.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Heading uses 'Part N' ceremony instead of a descriptive title (style guide A7): '%s'."
+level: warning
+scope: heading
+ignorecase: true
+raw:
+  - '^Part\s+([0-9]+|[IVXLC]+)\b'

doc/.vale/styles/Corosio/PartHeadings.yml

@@ -0,0 +1,68 @@
+# RETIRED AS AN AUTHORITY — demoted rather than deleted, the same treatment
+# .vale.ini gives the Google house-style pack. `doc/lint/sentence-length.mjs` is
+# the authority for C2 on both surfaces; this rule is kept only so that
+# `vale --minAlertLevel=suggestion` can still show what Vale made of a page.
+# `suggestion` is below .vale.ini's `MinAlertLevel = warning`, so it no longer
+# reaches baseline.json, the gate, or a default `vale modules` run.
+#
+# ============================================================================
+# DO NOT GATE THIS RULE. `--gate 'vale_adoc:Corosio\.SentenceLength$'` — the
+# obvious spec, by analogy with the working `vale_adoc:Corosio\.PartHeadings$` —
+# is VACUOUS. At `suggestion` this rule never enters a Vale fingerprint set, so
+# the spec matches nothing and the gate reports `gated: true, gatedNew: 0` and
+# exits 0 while checking NOTHING. Measured, exactly that. That is the same
+# fail-open shape as the vacuous `Corosio.PartHeadings` rule this branch already
+# had to fix. Gate the script instead:
+#
+#     --gate 'sentence_length:^C2:'
+#
+# which is live in docs.yml since the Phase-4 exit. Re-measured at the Phase-4
+# final fix wave: EXIT=1 / gatedNew=2, both findings the grandfathered
+# `when_any.hpp` refusals, so it still needs a baseline reseed before it can go
+# green. (An earlier version of this comment said gatedNew=135, the figure from
+# before the .adoc hard slice was worked to zero; `doc/lint/README.md` carried
+# the identical staleness and was corrected, this copy was missed.)
+# `^C2:` binds the HARD slice only; the design-essay
+# findings are keyed `advisory-C2` and are deliberately unreachable from a
+# `C2`-prefixed spec (doc/STYLE_GUIDE.md Part C2: hard in API docs, soft in
+# essays).
+# ============================================================================
+#
+# Three measured reasons this rule cannot be the authority, none fixable inside
+# a Vale rule (all `cwd=doc`, vale 3.15.1, target `modules`):
+#
+#   1. UNDER-COUNTS. It runs after .vale.ini's `TokenIgnores` blanks inline code
+#      spans, so a span contributes ZERO words where a reader counts one. Three
+#      measurements of the size of that blind spot, all agreeing:
+#        * task P4-prereq, Vale with rewritten TokenIgnores, on the
+#          pre-BlockIgnores-fix config:            140 -> 170   (+30)
+#        * this task, Vale with the committed TokenIgnores, every backtick span
+#          (2115) and `cpp:` macro (557) outside code blocks replaced by one
+#          word, `--minAlertLevel=suggestion`:     135 -> 164   (+29)
+#        * sentence-length.mjs, spans blanked versus spans as one word, all
+#          slices of `.adoc`:                      125 -> 152   (+27)
+#      An earlier version of this comment claimed "+35, measured twice" by
+#      substituting today's 135 for prereq's 140 and by counting words with
+#      Vale's tokenizer. Both were wrong; the real figure is +27 to +30.
+#   2. MIS-ATTRIBUTES, which is worse: the missed block produces no alert to
+#      chase, so re-running to a fixpoint never finds it. The blanking corrupts
+#      Vale's position mapping for `scope: sentence` rules. Hand-verified case:
+#      `5.buffers/5b.types.adoc` holds two over-limit sentences in list items
+#      (27 and 34 words) and Vale reports NONE. The artifact is not confined to
+#      `scope: sentence` either — a `Corosio.Terminology` alert on
+#      `4.coroutines/4b.launching.adoc` is reported at line 25, an `include::`
+#      line inside a `[source,cpp]` block, when the text that matched is at
+#      line 68.
+#   3. FALSE-POSITIVES on under-segmentation. `4.coroutines/4f.composition.adoc:93`
+#      is flagged as one sentence; its four real sentences are 23, 14, 11 and 6
+#      words. Reproduced with that paragraph alone in a file.
+#
+# Do NOT re-promote this to warning/error without first showing, on a fixture,
+# that Vale's position mapping for `scope: sentence` is fixed. Two checkers
+# reporting different C2 numbers is how a gate loses credibility.
+extends: occurrence
+message: "Sentence over 25 words — split it (style guide C1/C2)."
+level: suggestion
+scope: sentence
+token: \b(\w+)\b
+max: 25

doc/.vale/styles/Corosio/SentenceLength.yml

@@ -0,0 +1,48 @@
+# Deliberately scoped to the two literal tokens doc/STYLE_GUIDE.md Part C4 names
+# ("Avoid needless 'will' and 'has been'") — NOT extended to every perfect-tense
+# form. What this rule does and does not see, re-measured at commit 620fdf2c with
+# cwd=doc and PATH including node_modules/.bin (Vale shells out to asciidoctor for
+# .adoc, and the extracted docstrings are .adoc too):
+#
+# `will\s` IS wrap-tolerant, and that is deliberate. Commit 30464086 changed the
+# token from the space-literal `'will '` to `'will\s'`, so a `will` at the end of a
+# wrapped source line now matches. Fixture proof: `The buffer will\nbe consumed.`
+# is FLAGGED, Match `"will\n"`. Do not "simplify" this back to a literal space.
+#
+# `has been` is NOT wrap-tolerant — a known, open hole. Fixture proof: `The buffer
+# has\nbeen consumed.` is NOT flagged, while the same text on one line is. It costs
+# nothing today (0 occurrences of `has\s*\n\s*been` in either corpus at 620fdf2c),
+# so it is recorded rather than fixed; the fix is the same one-character change
+# (`has\sbeen`) if an instance ever appears.
+#
+# The perfect-tense family this rule deliberately excludes — 17 occurrences on the
+# docstring corpus (`doc/lint/.docstrings/`), plus 4 on the `.adoc` pages:
+#   have been           x12  (ex/this_coro.hpp x4, read_at_least.hpp x3,
+#                             write_at_least.hpp x3, ex/thread_pool.hpp,
+#                             write.hpp)
+#   has already been     x3  (when_any.hpp x2, ex/async_mutex.hpp)
+#   has not been         x1  (write_at_least.hpp)
+#   has now<newline>been x1  (ex/async_waker.hpp — invisible for BOTH reasons:
+#                             an intervening adverb and a line wrap)
+#   (.adoc: have been x2 in 4h.lambda-captures, 9l.RunApi; has <adv> been x2 in
+#    9b.Separation, why-corosio)
+# Maintainer ruling: these stay excluded. Part C4 names only "will" and "has been",
+# so the rule is FAITHFUL to the guide as written; extending `tokens` would be a
+# style-guide change smuggled in as a lint fix, and would surface ~17 new prose
+# findings at once. A future editor who wants broader coverage changes Part C4
+# first, then this file.
+extends: existence
+message: "Avoid needless future/perfect tense — prefer present simple (style guide C4): '%s'."
+level: warning
+ignorecase: true
+# `have been` and `had been` are the same present/past-perfect construct as
+# `has been`, which C4 names explicitly. Matching only the singular left a blind
+# spot a future author could write into freely: a raw grep found 8 live sites the
+# rule could not see (6 in published docstrings, 2 on pages), including one CI
+# surfaced only because a long single-line paragraph parses differently there.
+# All 8 were fixed when these tokens were added, so the rule stays at zero.
+tokens:
+  - 'will\s'
+  - 'has been'
+  - 'have been'
+  - 'had been'

doc/.vale/styles/Corosio/SimpleTense.yml

@@ -0,0 +1,36 @@
+# C10 / C.1 one-term-per-concept. Two things this rule has to get right at once,
+# and it got both wrong before: it must catch the verb in every form a writer
+# actually uses, and it must NOT touch API identifiers or the noun `launcher`.
+#
+# `ignorecase: false` plus bare stems meant only the exact lowercase stem was
+# seen. Measured on a fixture: `Launch the task for execution.`, `launches it on
+# the executor`, `launched`, `launching`, `Spawn`, `spawns`, `spawned`,
+# `spawning`, `Fire off`, `fires off`, `Kick off`, `kicked off` and `Boxed` all
+# passed; only `launch`, `cancellation token`, `cancel token` and `boxed` were
+# caught. That left the majority of real C10 prose invisible to the C10 checker.
+#
+# `ignorecase: true` is safe here, MEASURED rather than assumed. Every
+# `launch`/`spawn`-bearing identifier in the library and the pages is either
+# snake_case (`launch_one`, `launch_all`, `spawn_work`, `co_spawn`,
+# `launch_policies`, the snippet tag `4b_launching`) or a `launcher` compound
+# (`when_any_io_launcher`, `launchable`, `relaunch`, `launchers`). `_` is a word
+# character, so the `\b` after the stem already excludes the snake_case forms,
+# and the inflection list below is deliberately limited to VERB endings so it
+# cannot reach `launcher`. On top of that, `.vale.ini`'s `TokenIgnores` blanks
+# backtick spans and `cpp:` macros, so an identifier written as code is invisible
+# to this rule anyway.
+#
+# The noun `launcher` STAYS, and must not be flagged: it is the role name of the
+# `run_async` wrapper object, and plan Task 11's approved brief for all 18
+# overloads uses it — "Bind <options> to produce a launcher; invoke the launcher
+# with a task to start it." The verb `launch` is the violation, the noun
+# `launcher` is not. Verify both directions if you touch the pattern.
+extends: substitution
+message: "Use '%s' for one-term-per-concept consistency (style guide C.1)."
+level: warning
+ignorecase: true
+swap:
+  '\b(launch(?:es|ed|ing)?|spawn(?:s|ed|ing)?|fire[sd]? off|firing off|kick(?:s|ed)? off|kicking off)\b': start
+  '\bcancellation token\b': stop token
+  '\bcancel token\b': stop token
+  '\bboxed\b': type-erased