docs: fix audited contradictions, stale API; add documentation style guide#47
Merged
Conversation
…le guide Source-verified across the site (oracle = published 1.0.0): - interceptor chain order per ADR-024 on the homepage and auth guides (errorHandler -> auth -> authz -> otel -> validation) - generated #gen import convention (.ts), about.md opt-in resilience - auth header encoding, propagatedClaims, transportParityTest /parity import, router.rpc v2 signature, otel package layer, DlqOptions return type - contributing: Buf (not protoc), Node >=22.13.0 floor, dist-based scaffold - new contributing/documentation-style.md; nav Resources dropdown surfaces Migration; ADR-024 OTel placement note; architecture.md de-duplicated Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MdeH7fExPmiRHRirGuvGk3
…s out - Guide sidebar regrouped from 16 flat groups into 6 phases: Introduction, Build a Service, Connect Services, Secure, Operate, Deploy - the 15 package pages move to their own Packages nav section, grouped by layer - Architecture Overview and the floating single pages (Validation, Runtime Compatibility) placed in logical phases; no page URLs change Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MdeH7fExPmiRHRirGuvGk3
…rule Aligns the footer guidance with the existing READMEs, which use either the ASCII '--' em-dash (the prose convention, 9 packages) or a real em-dash; avoids a guideline that contradicts the shipped footers. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MdeH7fExPmiRHRirGuvGk3
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
Documentation-site fixes from a full audit against the published 1.0.0 surface
(oracle =
@connectum/*source, not prose or fixtures), plus a new style guideand a simpler top navigation.
Contradictions & stale API fixed
placed authentication outside
errorHandler. They now follow the documentedorder —
errorHandler → auth → authz → otel → validation— and the chaindiagrams agree with the code samples.
#gen/*convention is documented accurately(extension follows
buf.gen.yaml; run-directly projects use.ts), fixing thequickstart self-contradiction and the "always
.js" claim.about.md"Resilience by Default" → opt-in resilience; auth header encoding(roles JSON / scopes space-separated);
propagatedClaimsmoved off the JWTinterceptor;
transportParityTestimported from@connectum/testing/parity;router.rpcv2 signature;otelpackage layer;DlqOptions.errorSerializerreturn type.
protoc, the>=22.13.0consumer floor, and a dist-based new-package scaffold.
Additions
the canonical template for package READMEs and site pages.
Contributing, and Examples.
ADR-024note on OTel interceptor placement;architecture.mdde-duplicatedagainst the service-communication patterns page.
The site builds cleanly (no dead links). Part of a coordinated 1.0.0 docs pass
with companion PRs in the framework and examples repositories.
🤖 Generated with Claude Code
https://claude.ai/code/session_01MdeH7fExPmiRHRirGuvGk3