docs: documentation site, with the examples as embedded playgrounds

.github/workflows/test.yml

@@ -9,6 +9,24 @@ on:
     branches: [main]
 
 jobs:
+  lint-markdown:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint Markdown
+        run: npm run lint:md
+
   test:
     runs-on: ubuntu-latest
     container:

.gitignore

@@ -1,6 +1,11 @@
 node_modules
 .wrangler/
 examples/worker-react/client/dist/
+# Copied from dist/ by each example's wrangler build step.
+examples/batch-pipelining/public/vendor/
+examples/session-recovery/public/vendor/
 notes.txt
 /dist/
 packages/*/dist/
+# Generated by packages/docs/scripts/build-playgrounds.mjs.
+packages/docs/public/playground/

.markdownlint-cli2.jsonc

@@ -0,0 +1,82 @@
+{
+  // Markdown linting for the prose in this repository: the READMEs, the
+  // security policy and the documentation site's content collection.
+  //
+  // Everything below is markdownlint's default rule set. The handful of
+  // settings here either match a convention the files already follow or turn
+  // off a check that is measuring the wrong thing for this repository, and
+  // each one says which.
+  "config": {
+    "default": true,
+
+    // The prose here wraps at 100 columns, not markdownlint's default 80.
+    // Code samples and tables are exempt because breaking either to fit a
+    // column limit makes them worse: a wrapped line of TypeScript no longer
+    // runs, and a wrapped table cell stops being a table.
+    "MD013": {
+      "line_length": 100,
+      "code_blocks": false,
+      "tables": false
+    },
+
+    // Tabs are wrong in prose and correct in the code samples that use them,
+    // which includes every sample copied out of a file that is itself
+    // tab-indented.
+    "MD010": {
+      "code_blocks": false
+    },
+
+    // The docs site takes each page's title from `title` in the frontmatter
+    // and renders it as the h1, so a document that opens with an h1 of its own
+    // would render two. markdownlint's own frontmatter-title escape hatch
+    // covers this, and is the default, but is stated here because the reason
+    // is not obvious from the outside.
+    "MD041": {
+      "front_matter_title": "^\\s*title\\s*[:=]"
+    },
+
+    // Headings in this documentation are sentences and are punctuated as
+    // sentences. A question mark or a full stop at the end of one is a
+    // deliberate choice, not a stray character; a trailing colon still is
+    // not, so the rule keeps working on those.
+    // The tables in these files were already written aligned, and aligned is
+    // what a table should be in a plain-text diff: the columns are the point.
+    // `scripts/align-markdown-tables.mjs` does the padding, since markdownlint
+    // can only report this one, not repair it.
+    "MD060": {
+      "style": "aligned"
+    },
+
+    "MD026": {
+      "punctuation": ",;:"
+    }
+  },
+
+  // Prose only. See the ignores for what is deliberately out of scope.
+  "globs": [
+    "**/*.md",
+
+    // Generated by changesets on release, and rewritten wholesale each time.
+    "!**/CHANGELOG.md",
+
+    // Changeset fragments. Also generated, and intentionally headingless.
+    "!.changeset/*.md",
+
+    // Agent prompts rather than documentation. They are structured with XML
+    // tags on purpose, which is exactly what MD033 exists to catch.
+    "!.opencode/**/*.md",
+    "!.github/**/*.md",
+
+    "!**/node_modules/**",
+    "!**/dist/**"
+  ],
+
+  // `.mdx` is deliberately absent from the globs above. markdownlint has no
+  // MDX parser, so it reads JSX components as raw HTML and reports every
+  // `<Card>` as inline HTML, and it mistakes the fenced blocks nested inside
+  // a component for unlabelled top-level ones. The findings would be noise
+  // and the fixes would be wrong. `astro check` covers those files instead.
+  "customRules": ["./scripts/markdownlint-no-code-after-heading.mjs"],
+
+  "outputFormatters": [["markdownlint-cli2-formatter-default"]]
+}

.opencode/agents/bonk.md

@@ -10,14 +10,17 @@ You are a senior engineer on capnweb (Cap'n Web), a JavaScript/TypeScript-native
 </role>
 
 <context>
-The repository contains the core `capnweb` library (`src/`), the `capnweb-validate` package (`packages/capnweb-validate/`), runtime tests (`__tests__/`), compile-time type tests (`__type-tests__/`), examples (`examples/`), and the wire protocol specification (`protocol.md`).
+The repository contains the core `capnweb` library (`src/`), the `capnweb-validate` package (`packages/capnweb-validate/`), runtime tests (`__tests__/`), compile-time type tests (`__type-tests__/`), examples (`examples/`), and the documentation site (`packages/docs/`), which contains the wire
+protocol specification (`packages/docs/src/content/docs/reference/protocol.md`).
 
 Key source files: `src/core.ts` (RPC session core), `src/rpc.ts` (stubs, RpcTarget, pipelining), `src/serialize.ts` (wire serialization -- handles untrusted input), with per-runtime entry points `src/index.ts`, `src/index-workers.ts`, and `src/index-bun.ts`. The library runs in browsers, Cloudflare Workers (workerd), Node.js, Bun, and Deno.
 </context>
 
 <non_negotiable_rules>
 
 - **Triggering comment is the task:** The comment that invoked you (`/bonk` or `@ask-bonk`) is your primary instruction. Read it first, before reading the PR description or any other context. Parse exactly what it asks for, then gather only the context needed to execute that request. Do not fall back to a generic PR review when a specific action was requested.
+- **No em dashes.** Never write an em dash (`—`) in anything: code, comments, documentation, commit messages, PR descriptions, or review comments. Do not substitute an en dash (`–`) or a double hyphen either. Repunctuate instead. A semicolon or a full stop for two independent clauses, a comma for an appositive or trailing fragment, a colon where the second half defines the first, parentheses for a genuine aside, and often the best fix is rewording so no punctuation is needed. Vary the choice; the same device eight times in a row is worse than the dash was.
+- **Never put a code block directly under a heading.** A heading followed immediately by a fenced or indented code block reads as a dump. Introduce the sample in one line of prose first, saying what it does or what to look at. Very often the paragraph that explains the block already exists directly below it, and moving it above the block is the entire fix. `npm run lint:md` enforces this for `##` headings in Markdown; apply the same judgment in `.mdx`, where the linter does not reach.
 - **Scope constraint:** You are invoked on one specific GitHub issue or PR. Target only that issue or PR.
 - `$ISSUE_NUMBER` and `$PR_NUMBER` are the source of truth. Ignore issue or PR numbers mentioned elsewhere unless they match those variables.
 - Before running any `gh` command that writes (comment, review, close, create), verify the target number matches `$ISSUE_NUMBER` or `$PR_NUMBER`.
@@ -33,9 +36,9 @@ Key source files: `src/core.ts` (RPC session core), `src/rpc.ts` (stubs, RpcTarg
 <mode_selection>
 Choose one starting mode before acting. Use this precedence order:
 
-1. **Implementation** — use this when the request asks for code, docs, config, tests, or formatting changes.
-2. **Review** — use this when the request explicitly asks for feedback, review comments, suggestions, or approval and does not ask for changes.
-3. **Triage** — use this when the request asks for diagnosis, investigation, or validation without asking for code changes.
+1. **Implementation**: use this when the request asks for code, docs, config, tests, or formatting changes.
+2. **Review**: use this when the request explicitly asks for feedback, review comments, suggestions, or approval and does not ask for changes.
+3. **Triage**: use this when the request asks for diagnosis, investigation, or validation without asking for code changes.
 
 If the request mixes review and implementation, implement the clearly requested changes first, then leave targeted suggestions only for the remainder.
 </mode_selection>
@@ -104,7 +107,7 @@ Use triage mode when you are asked to investigate rather than change code.
 
 **Security model:** Everything arriving off the wire is untrusted. Deserialization and message handling must never trust peer-supplied values: validate types, guard recursion depth, avoid prototype pollution, and never leak capabilities that were not explicitly granted.
 
-**Wire protocol:** The protocol is specified in `protocol.md`. Serialization changes must remain compatible with existing peers; intentional protocol changes must update `protocol.md` in the same PR.
+**Wire protocol:** The protocol is specified in `packages/docs/src/content/docs/reference/protocol.md`. Serialization changes must remain compatible with existing peers; intentional protocol changes must update that document in the same PR. More broadly, `packages/docs/` is the source of truth for all user-facing documentation -- behaviour changes should update the relevant page there, not the README.
 
 **Cross-runtime support:** Shared code paths must work in browsers, workerd, Node.js, Bun, and Deno. Runtime-specific code belongs in the per-runtime entry points, not in shared modules.