Reorganize docs: visual-first README, topic pages, inline diagrams - #117
Merged
Conversation
The README had grown to ~1100 lines of solid text, with every diagram exiled behind a "Prefer pictures?" link to docs/architecture.md. Flip that: the README is now a ~230-line visual-first overview, and the deep reference lives in topic pages with the diagrams inline next to the prose they illustrate. README (rewritten): - New hero diagram docs/img/lifecycle.svg — hand-drawn in the existing SVG house style (theme-neutral, transparent) rather than Mermaid, so it renders on npmjs.com too, where Mermaid does not. - context-accumulation.svg and htpipe-composition.svg now appear inline in the overview; a Documentation table maps the topic pages. - Keeps: hero example, install, no-magic longhand, philosophy, trimmed FAQ, roadmap pointer, license, the name story. New topic pages (content moved, not rewritten): - docs/lifecycle.md — stages in detail, slices & strictness, raw-request split (both Mermaid views) - docs/composition.md — HTPipe, routes file, partial pipelines, finishPipe, type troubleshooting (+ htpipe & stage-dep SVGs) - docs/errors.md — error vocabulary, bodies, unexpected-error routing, the auth gate (+ failure-routing Mermaid, corrected for 1.1.0: extractAmbient unknown throws are on the 500 row, not 422) - docs/adapters.md — responseMeta, adapter options, all five framework adapters, define* helpers (+ adapters SVG) - docs/validation.md — zod helpers, codecs, switches - docs/mongoose.md — factory, everyday loaders & ctxRef, tenant scoping - docs/README.md — index; docs/architecture.md reduced to a pointer stub so old links land somewhere useful Also: - typedoc.json: add the src/ctx-ref.ts entry point missed in 1.1.0, so the new subpath appears in the generated API reference - Cross-page links fixed for the new layout; verified all image and page links resolve and typedoc builds clean Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HoGnocn8JV1iaXxdnwA5ir
A chunk-level audit (old README + architecture.md vs the new corpus) caught three genuine information losses among the deliberate trims: - docs/README.md: the full runnable-examples block (per-adapter commands and the "examples import from ../src" note), previously in the README - README install: the explicit node10 caveat — legacy "node" resolution cannot see the subpath type declarations - docs/adapters.md (tRPC): the single-input note — tRPC has one input value, not the HTTP slot shape; the adapter decides what sanitizeInputs receives Everything else flagged by the audit is a verified reword or an intentional edit (link retargets for the new layout, the corrected failure-routing diagram, condensed hero/FAQ prose). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HoGnocn8JV1iaXxdnwA5ir
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
2 participants
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.
What does this PR do?
Makes hipthrusts an easy sell up front. The README had grown to ~1100 lines of solid text, with every diagram exiled behind a "Prefer pictures?" link — the reverse of what a first-time visitor needs. This flips it.
README → ~230-line visual-first overview
docs/img/lifecycle.svg): the eight-stage pipeline with failure drop-outs, the context-accumulation strip, required/optional legend, and the "missing a required stage cannot ship" punchline. Hand-drawn in the existing SVG house style rather than Mermaid so it renders on npmjs.com too (npm doesn't render Mermaid; it does render repo-relative SVGs).context-accumulation.svgandhtpipe-composition.svgnow appear inline in the overview.Deep reference → six topic pages (content moved, not rewritten)
docs/lifecycle.mddocs/composition.mddocs/errors.mddocs/adapters.mddefine*helpers + SVGdocs/validation.mddocs/mongoose.mddocs/README.mdis the index;docs/architecture.mdis reduced to a pointer stub so old links land somewhere useful.Corrections along the way
extractAmbienton the 422 row — stale since 1.1.0's fix routed its unknown throws to 500. Corrected indocs/errors.md.typedoc.jsonwas missing thesrc/ctx-ref.tsentry point added in 1.1.0, so the new subpath's exports were absent from the generated API reference. Added —ctx-ref.htmlnow builds.Verified
🤖 Generated with Claude Code
https://claude.ai/code/session_01HoGnocn8JV1iaXxdnwA5ir
Generated by Claude Code