docs: enforceable doc-spec, slimmer README, migration guides - #7
Merged
Merged
Conversation
Apply the doc-spec frontmatter schema (title, description, section, audience, status, optional related) to every doc in the tree, making the documentation contract real tree-wide. 29 files gain frontmatter; the four contract-authored pages already had it. The Swaggo migration gap audit is marked status: internal per the spec's treatment of in-tree trackers. No ad-hoc callouts were present to convert. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Break the overloaded rpc/docs-and-clients.md into two focused pages and add the three decision trees readers were missing. - rpc/serving-docs.md: serving mechanics (modules, ServeDocs, ServeAllDocs, DocsHandler, AdminHandler, hash endpoints) with a "which serving call?" decision table. Observability how-to now links to the patterns cookbook instead of duplicating it. - rpc/scalar-auth-cors.md: guard-to-OpenAPI-scheme mapping, same-origin and cross-origin docs, and CORS. - Delete rpc/docs-and-clients.md; repoint rpc/overview.md and rpc/patterns.md. - http-legacy/typed-handlers.md: add a WrapFunc vs TypedHandlerFunc vs struct TypedHandler decision table. - concepts/rpc-vs-httpapi.md: add an RPC vs httpapi decision table. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Move the Swaggo migration gap audit out of the published docs tree into _design/ (its frontmatter stripped to match sibling design docs) and list it in the specs index. It is an internal tracker, not published guidance. - Add "Part of the Agents hub" back-links to contract.md, client-codegen.md, and python-codegen-rules.md, which previously only linked forward. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Show the generated client: a typed TS call right after the quickstart, so the payoff (no hand-written types or fetch boilerplate) is visible. - Add a "Using a coding agent?" tip linking the agents hub — cashing in the agent-first headline. - Add a scannable Features list and a compact table of contents. - Add pkg.go.dev and Go Report Card badges, and a pre-1.0 stability note. - Add an Examples section linking the five runnable example apps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
Overhauls the documentation so it matches Virtuous's "runtime truth, no drift" philosophy — the docs now follow their own contract, the README leads with the payoff, and migration paths are first-class.
Done across 5 commits:
docs/doc-spec.mdfrom ALL-CAPS plaintext into a contract that obeys itself: a lighter required frontmatter schema, heading discipline, gofmt-clean language-tagged code, and GitHub-native callouts. The unbuilt machinery (SSG, JSON agent-index, versioned URL trees) is parked in an explicit "Not yet" section so the spec stops claiming capabilities that don't exist.main()indentation, resolved the httpapi voice to "HTTP-native library" (not "legacy"), and moved both cookbooks into the docs tree. Then enhanced: a generated-client payoff snippet, an agent callout, a Features list + TOC, pkg.go.dev / Go Report Card badges, an Examples section, and a pre-1.0 status note.docs/tutorials/coming-from-routers.md(concept map + before/after recipes for gin/echo/chi/fiber/net-http) alongside the existing Swaggo guide.docs/rpc/patterns.mdanddocs/http-legacy/patterns.md.rpc/docs-and-clients.md→rpc/serving-docs.md+rpc/scalar-auth-cors.md, plus three new decision trees (RPC vs httpapi; ServeDocs vs DocsHandler vs AdminHandler; WrapFunc vs TypedHandlerFunc vs struct TypedHandler)._design/, added agent-hub back-links.Validation
main()indentation bug is fixed.🤖 Generated with Claude Code