docs: readability pass, port explanations, and smaller linked files - #59
Merged
Conversation
… doc The hexagon diagram's boxes are now named themes with a note saying they are not layers, and every one of the 15 ports gets a plain what-and-why line. The e2e doc splits into a how-to README and a design.md for the reasoning, fixing a duplicated breadcrumb. CONTEXT.md's intro drops the cleverness and the small overloads collapse into one table. Claude-Session: https://claude.ai/code/session_01FSkESkJTRpt3Ye2cM7c5n5
…doc note CLAUDE.md keeps every fact and loses every dash and sentence colon, with the dense packaging bullet split in two. CONTRIBUTING drops the boilerplate gush and states the policy in four lines. The OpenAPI note in the generator template breaks into bullets so every regeneration inherits the readable form. Claude-Session: https://claude.ai/code/session_01FSkESkJTRpt3Ye2cM7c5n5
Ran a readability pass over all eight ADRs. Broke every Decision paragraph that ran past four lines into one bullet per decision element, especially 0005 and 0006 which were dense single paragraphs. Removed a few clever turns of phrase and simplified redundant contrasts. Fixed a stray colon used as sentence punctuation and a mismatched verb pair in 0007's downgrade sentence. No facts, numbers, paths, or technical claims changed. Claude-Session: https://claude.ai/code/session_01FSkESkJTRpt3Ye2cM7c5n5
…on docs Ran the same readability pass over the nine folder-level READMEs. Broke up run-on paragraphs, split a few comma splices into separate sentences, and reflowed server/migrations/README.md out of its old hard-wrapped lines to match every other doc in the repo. Replaced "harness" in server/README.md's file table with "helpers" to avoid a banned puffery word, even though the folder holds a file literally named route-harness.ts. Flagging that swap in case the literal filename match was worth more than the word ban. No facts, numbers, paths, or technical claims changed otherwise. Claude-Session: https://claude.ai/code/session_01FSkESkJTRpt3Ye2cM7c5n5
The banned word list targets puffery and this is the literal filename the table points at. Claude-Session: https://claude.ai/code/session_01FSkESkJTRpt3Ye2cM7c5n5
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.
A docs-only pass driven by three owner requests.
What changed
Verification
https://claude.ai/code/session_01FSkESkJTRpt3Ye2cM7c5n5