docs: rewrite README as a landing page; move reference content into docs/ - #68
Conversation
…ocs/ The README was a landing page welded to the pre-Diátaxis reference manual (863 lines, first code at line 187, a Vercel comparison table before Install). Rewrite it as a ~200-line landing page: value proposition, a complete build-checked hello-world Slack bot, install, feature highlights linking into docs/, adapter maturity, the Diátaxis index, the Vercel relationship in three sentences, short non-goals, and status. Relocate every removed reference section into its Diátaxis home: runtime semantics by concept plus per-adapter status and the testing contract into docs/reference.md; design goals, the Vercel comparison table, the long-form non-goals, and the intentional gaps into docs/explanation.md. Dedupe against existing how-tos rather than paste, and fix two stale how-to claims found on the way (lost lock lease cancels the handler with ErrPreempted; block_actions admission rejection is a 503, only slash commands get the busy text). documentation_test.go: retarget every README phrase assertion to the phrase's new home (none removed) and add TestREADMEMarkedSnippetsBuild, which compiles the README's marked Go block against the module.
|
@codex review |
|
@codex security review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Codex Review: Didn't find any major issues. Chef's kiss. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
Security review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
1 participant
Rewrites
README.mdfrom a landing page welded to the pre-Diátaxis reference manual into an actual landing page, and relocates every removed reference section into its Diátaxis home underdocs/. No information was deleted: sections moved, were deduplicated against whatdocs/already said, and were re-verified against the code where the two disagreed.Before / after
README.mddocs/reference.mddocs/explanation.mddocs/README.mddocs/how-to/deferred-dispatch.mddocumentation_test.goNew README
Title + badges (CI, pkg.go.dev, latest release — all three verified to render) → one-paragraph value proposition for a Go platform engineer → a complete 45-line hello-world Slack bot (build-checked, see below) → Install (Go 1.26.3, root + state modules) → Features (each bullet links to its how-to or reference section) → Adapters (maturity table, tightened) → Documentation (Diátaxis index) → Relationship to Vercel Chat SDK (3 sentences + link) → Non-goals (5 one-liners linking to the long form) → Status.
Section relocation map
README.md(rewritten value proposition;## Adapters)docs/explanation.md#design-goalsdocs/explanation.md#vercel-chat-sdk-alignmentREADME.md#install; layout indocs/reference.md#modules-and-packagesdocs/reference.md#examplesREADME.md#hello-slackprogramdocs/reference.md#runtime-constructionand#ephemeral-messages(Redis wiring already indocs/how-to/choose-a-state-backend.md)docs/reference.md#core-modeldocs/reference.md#runtime-constructiondocs/reference.md#webhooksdocs/reference.md#routing,#command-and-interaction-eventsdocs/reference.md#observabilitydocs/reference.md#dispatch-and-acknowledgementdocs/reference.md#runtime-statedocs/reference.md#dedupe-locks-and-concurrencydocs/reference.md#messages,#ephemeral-messagesdocs/reference.md#message-historydocs/reference.md#actors-and-identitydocs/reference.md#adapter-accessdocs/reference.md#slack-adapter,#linear-adapter(merged with the existing capability table)README.md#non-goals(short) +docs/explanation.md#non-goals(long form)docs/explanation.md#intentional-gapsdocs/reference.md#testing-contractdocs/README.mdindex descriptions updated for the expanded reference and explanation pages.Code-is-truth fixes found while relocating
docs/how-to/deferred-dispatch.mdsaid a lost lock lease lets the handler "keep running without exclusivity".runtime.gostartLockRefreshcancels the handler withchat.ErrPreemptedas the context cause (as the README correctly said). Fixed.adapters/slack/interactive.goreturns 503 forblock_actionsand the 200 + busy text only for slash commands. Wording made precise.preempted/admission-rejectedspan outcomes and theadmission_rejectedpoint event (observer.go), which the README omitted.Tests
TestDocumentationCoversIntentionalVercelDifferencesandTestDocumentationCoversMessageHistoryCapability: every phrase assertion retained and retargeted to the phrase's new home (README.mdkeeps "not a TypeScript API port";docs/reference.mdanddocs/explanation.mdtake the rest). No assertion weakened or removed.TestREADMEMarkedSnippetsBuild: every<!-- build -->-marked Go block inREADME.mdis written into a temporary_readme_snippet_*package under the root module and mustgo build, so the hello-world can never silently rot. The underscore prefix keeps a stray directory out of./...; the test is sequential so itsgo buildcannot skew the timing-sensitive dispatch tests.Validation
mise run vet— passGOFLAGS=-race mise run test— passREADME.mdanddocs/**/*.md— 30 files, 0 broken (checker negative-tested)image/svg+xml; release badge shows v0.2.0Note for the maintainer
The repository has no
LICENSEfile (GitHub reportslicense: null), so the README deliberately has no license line rather than inventing one. Worth deciding before promoting the landing page further.Generated with
mux• Model:anthropic:claude-fable-5-1• Thinking:xhigh