docs: make repository docs canonical

.dev/docs_check.ts

@@ -0,0 +1,59 @@
+/**
+ * Verifies that the repository-native documentation stays complete and GitHub-renderable.
+ *
+ * @module
+ */
+
+import { readdir } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT_DIR: string = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DOCS_DIR: string = join(ROOT_DIR, "docs");
+const SUMMARY_PATH: string = join(DOCS_DIR, "SUMMARY.md");
+
+async function markdownFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await markdownFiles(path)));
+    } else if (entry.name.endsWith(".md")) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+
+function fail(messages: readonly string[]): never {
+  throw new Error(`Documentation check failed:\n${messages.map((message) => `- ${message}`).join("\n")}`);
+}
+
+const files: string[] = (await markdownFiles(DOCS_DIR)).sort();
+const relativeFiles: string[] = files.map((path) => relative(DOCS_DIR, path));
+const pages: string[] = relativeFiles.filter((path) => path !== "SUMMARY.md");
+const summary: string = await Bun.file(SUMMARY_PATH).text();
+const summaryLinks: string[] = [...summary.matchAll(/\]\(([^)#?]+\.md)(?:#[^)]+)?\)/g)].map((match) => match[1]!);
+
+const errors: string[] = [];
+const duplicateLinks: string[] = summaryLinks.filter((link, index) => summaryLinks.indexOf(link) !== index);
+if (duplicateLinks.length > 0) {
+  errors.push(`SUMMARY.md contains duplicate pages: ${[...new Set(duplicateLinks)].join(", ")}`);
+}
+
+for (const page of pages) {
+  if (!summaryLinks.includes(page)) errors.push(`SUMMARY.md is missing ${page}`);
+}
+for (const link of summaryLinks) {
+  if (!pages.includes(link)) errors.push(`SUMMARY.md links to a missing or non-page file: ${link}`);
+}
+
+for (const path of files) {
+  const source: string = await Bun.file(path).text();
+  if (source.includes("{%")) {
+    errors.push(`${relative(DOCS_DIR, path)} contains unsupported GitBook directives`);
+  }
+}
+
+if (errors.length > 0) fail(errors);
+console.log(`Documentation index covers all ${pages.length} pages; no GitBook directives found.`);

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# @joeblau is the maintainer for this repository.
+* @joeblau

.github/CONTRIBUTING.md

@@ -30,14 +30,14 @@ Every task in this repo runs through Bun. There is no other toolchain.
 | Command                        | What it does                                                         |
 | ------------------------------ | -------------------------------------------------------------------- |
 | `bun install`                  | Install dependencies.                                                |
-| `bun run check`                | Format, lint, TypeScript 5 + 7 types, JSDoc sync, export sync.       |
+| `bun run check`                | Format, lint, docs, TypeScript 5 + 7, JSDoc sync, export sync.       |
 | `bun test tests/`              | Full test suite; the online tests need network and credentials.      |
 | `HL_OFFLINE=1 bun test tests/` | Offline gate: skips every live-endpoint test. This is what CI runs.  |
 | `bun run perf`                 | Performance suite; prints a table (`--out <path>` writes JSON).      |
 | `bun run perf:gate`            | Zero-performance-regression gate (see below).                        |
 | `bun run build`                | Emit the publishable package into `dist/`.                           |
 
-`bun run check` is a bundle of narrower scripts (`check:format`, `check:lint`, `check:types`, `check:ts7`,
+`bun run check` is a bundle of narrower scripts (`check:format`, `check:lint`, `check:docs`, `check:types`, `check:ts7`,
 `check:jsdoc`, `check:export`) — run one directly when you only want to re-check that dimension. `bun run format` and
 `bun run lint` are the `--write` variants of the first two.
 
@@ -86,7 +86,7 @@ that change. If the gate flaps on a busy machine, widen the band with `--thresho
 
 ## Coding Guidelines
 
-- **Style**: After making all changes, run: `bun run check` (format, lint, TypeScript 5, TypeScript 7, doc/export sync).
+- **Style**: After making changes, run `bun run check` (format, lint, docs, TypeScript 5 + 7, JSDoc/export sync).
 - **Performance**: Zero-regression policy — if you touch a hot path, run `bun run perf:gate` before opening a PR.
 - **Dependencies**: Use small and easily auditable dependencies (e.g.
   [@noble/hashes](https://www.npmjs.com/package/@noble/hashes) or [valibot](https://valibot.dev/)).

.github/workflows/code_quality.yml

@@ -25,8 +25,9 @@ jobs:
       # package.json calls `check` "everything CI gates on", and enumerating the steps here is how that
       # claim silently becomes false (it already had — the two sync gates below were missing entirely).
       #
-      # `check` runs, in order: biome format, biome lint, TypeScript 5 typecheck, the TypeScript 7
-      # forward-compatibility gate (own install tree under .dev/ts7, since TS7 ships a native binary
-      # with no JS compiler API), the JSDoc sync check and the export sync check.
+      # `check` runs, in order: biome format, biome lint, repository-native documentation checks,
+      # TypeScript 5 typecheck, the TypeScript 7 forward-compatibility gate (own install tree under
+      # .dev/ts7, since TS7 ships a native binary with no JS compiler API), the JSDoc sync check and
+      # the export sync check.
       - name: Check
         run: bun run check

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Documentation
+
+on:
+  pull_request:
+    paths:
+      - "README.md"
+      - "docs/**"
+      - ".dev/docs_check.ts"
+      - ".github/CODEOWNERS"
+      - ".github/workflows/docs.yml"
+      - ".lycheeignore"
+      - ".markdownlint-cli2.jsonc"
+      - "package.json"
+      - "bun.lock"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          # Match the rest of CI while Bun 1.4 remains canary-only.
+          bun-version: canary
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Check documentation structure and formatting
+        run: bun run check:docs
+
+      - name: Check documentation links
+        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2
+        with:
+          args: >-
+            --root-dir .
+            --no-progress
+            --max-retries 3
+            --timeout 20
+            README.md
+            'docs/**/*.md'
+          fail: true
+          failIfEmpty: true
+          token: ${{ secrets.GITHUB_TOKEN }}

.lycheeignore

@@ -0,0 +1 @@
+^https://www\.npmjs\.com/package/@bloxwap/hyperliquid$

.markdownlint-cli2.jsonc

@@ -0,0 +1,11 @@
+{
+  "config": {
+    // This repository wraps prose at 120 columns, while the markdownlint default is 80.
+    "MD013": false,
+    // Separate GitHub alert blocks use blank quoted lines by design.
+    "MD028": false,
+    // The root README starts with centered HTML branding, and embedded HTML is intentional there.
+    "MD033": false,
+    "MD041": false
+  }
+}

README.md

@@ -24,27 +24,31 @@
 - **Integratable**: Easy to use with [viem](https://github.com/wevm/viem) accounts — local (private key) or JSON-RPC
   (browser wallet).
 
+## Documentation
+
+Browse the [SDK documentation](docs/README.md) for installation, clients, transports, signing, utilities, and guides.
+
 ## Installation
 
-**Bun 1.3.3+**
+### Bun 1.3.3+
 
 ```sh
 bun add @bloxwap/hyperliquid
 ```
 
-**Node.js 22.12+ / React Native 0.86+**
+### Node.js 22.12+ / React Native 0.86+
 
 ```sh
 npm i @bloxwap/hyperliquid
 ```
 
-**pnpm**
+### pnpm
 
 ```sh
 pnpm add @bloxwap/hyperliquid
 ```
 
-**Yarn**
+### Yarn
 
 ```sh
 yarn add @bloxwap/hyperliquid
@@ -141,6 +145,7 @@ await subs.l2Book({ coin: "ETH" }, (data) => {
 ```
 
 > [!WARNING]
+>
 > - **Never hardcode private keys** in source or commit them to git. Load them from environment variables or a secret
 >   store (Bun auto-loads a local `.env`, which is gitignored in this repo).
 > - For trading bots, prefer a Hyperliquid **agent wallet** (API wallet) over the master account key: an agent key can