docs: refresh AGENTS.md + docs/* for verbose flag + on_wire callback#7
Merged
Conversation
Add a "Logging posture" paragraph to the stack overview covering the silent-by-design library, the CLI -v/--verbose flag, and the on_wire: callback kwarg on Miner.new / MinerPool.new with its three directions (:request, :response, :response_repaired). Add a structural fact noting on_wire is best-effort telemetry wrapped in safe_on_wire so a buggy callback cannot break a query. Add -v usage to the manual sandbox block and a docs/logging.md row to the deep-context table. Refresh the SLOC footprint to match post-verbose-flag reality.
Add on_wire: keyword-arg usage to Miner.new and MinerPool.new signatures in interfaces.md; document the CLI -v/--verbose flag with its actual direction prefixes (>>>, <<<, <<< (repaired)) and mutex-serialized write behavior; cross-link to docs/logging.md for the full posture. Fix error class references in logging.md — the stub's initial wording named SocketReadTimeout / ProtocolError, which are not real classes. Replace with the actual public hierarchy (Error, ConnectionError, TimeoutError, ApiError) and describe the pool's failure-capture contract. Add sections documenting the on_wire: library hook (three directions, safe_on_wire swallowing) and the CLI flag (defensive EPIPE/IOError handling so stderr closure doesn't break the query).
Add on_wire: kwarg to the Miner and MinerPool constructor summaries in components.md; note that MinerPool forwards the callback into every Miner it constructs. Describe safe_on_wire's three directions and exception-swallowing contract. Update the bin/cgminer_api_client entry to document the -v/--verbose flag and the mutex-serialized stderr writer with EPIPE/IOError defenses. In workflows.md, extend the single-miner request-flow sequence diagram with the three safe_on_wire call sites (request / response / response_repaired) and add a key observation pointing at logging.md.
Bash wrapper around npx @mermaid-js/mermaid-cli that extracts every ```mermaid block under docs/*.md and pipes each through the parser, reporting Parse/Lexical errors. Exits non-zero on any failure so a CI job can opt in later. Not wired into bundle exec rake — first run pulls Puppeteer+Chromium (~300MB) into ~/.npm/_npx, which is too heavy to impose on every test cycle. Documented in AGENTS.md "Running tests and lint" as an opt-in local check for docs PRs. All five api_client diagrams validate clean — the monitor and manager PRs in this docs-refresh round each caught real drift, so bundling the same tool here keeps the three repos symmetric for future edits.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The recent CLI
-v/--verboseflag, the library-levelon_wire:callback onMiner.new/MinerPool.new, and the newdocs/logging.mdstub had landed in code, README, and CHANGELOG — but the long-form docs and AGENTS.md still described the pre-verbose-flag world.Three commits, one surface each:
docs(agents): document verbose flag, on_wire callback, logging.md— AGENTS.md stack overview gains a "Logging posture" paragraph; structural-facts list gains asafe_on_wireentry; sandbox block demonstrates-v; deep-context table routes todocs/logging.md.docs(interfaces,logging): document -v/--verbose and on_wire: hook—Miner.newandMinerPool.newsignatures ininterfaces.mdshowon_wire:usage; a new "Flags" table documents-v/--verbosewith the actual direction prefixes (>>>,<<<,<<< (repaired)). Drive-by fix indocs/logging.md: the initial stub named non-existent error classes (SocketReadTimeout,ProtocolError) — replaced with the actual public hierarchy (Error,ConnectionError,TimeoutError,ApiError) and the pool's failure-capture contract.docs(components,workflows): document on_wire: hook + CLI -v wiring—Miner/MinerPool/bin/cgminer_api_clientcomponent entries pick up the constructor shapes and the CLI flag's mutex-serialized stderr writer with EPIPE/IOError defenses; the single-miner sequence diagram shows the threesafe_on_wirecall sites.Docs-only, no code changes.
Test plan
bundle exec rakegreen (spec + rubocop; coverage 99.69%).git diff --stat origin/develop..— 5 files touched, all underdocs/orAGENTS.md.