tableau · StefanSteiner · Sep 6, 2026 · Sep 5, 2026 · Sep 5, 2026 · Sep 5, 2026
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -24,6 +24,12 @@
     // reference, so hand-edits are undone by the next refresh.
     "hyperdb-mcp/scripts/dc_sql_reference.md",
 
+    // Root changelog only. release-please generates it -- it is the sole
+    // "changelog-path" in release-please-config.json -- so any hand-fix is
+    // clobbered on the next release. Deliberately NOT "**/CHANGELOG.md": the
+    // nine per-crate changelogs are hand-maintained and stay in scope.
+    "CHANGELOG.md",
+
     // npm platform sub-packages: packaging boilerplate, largely generated
     "hyperdb-api-node/npm/**",
     "hyperdb-mcp/npm/**"

diff --git a/.markdownlintignore b/.markdownlintignore
@@ -13,6 +13,14 @@ test_results/
 # so hand-editing it is undone by the next refresh.
 hyperdb-mcp/scripts/dc_sql_reference.md
 
+# Root changelog only -- release-please generates it (the sole changelog-path
+# in release-please-config.json), so hand-fixes are clobbered on the next
+# release. The leading slash is load-bearing: an unanchored "CHANGELOG.md"
+# would also hide the nine hand-maintained per-crate changelogs, which are in
+# scope. (markdownlint-cli2 matches its own list as globs, not gitignore
+# patterns, so the equivalent entry there needs no slash.)
+/CHANGELOG.md
+
 # npm platform sub-packages: packaging boilerplate, largely generated
 hyperdb-api-node/npm/
 hyperdb-mcp/npm/
diff --git a/AGENTS.md b/AGENTS.md
@@ -43,7 +43,7 @@ This is a **pure-Rust implementation** of the Hyper database API, using the Post
 
 The codebase uses a **layered architecture**. The flagship user-facing crate is `hyperdb-api`; its implementation details live in `hyperdb-api-core`, which preserves three internal submodules (`types`, `protocol`, `client`) that contributors navigate independently. Two optional companion crates extend the public surface.
 
-```
+```text
 ┌─────────────────────────────────────────────────────┐
 │  hyperdb-api (High-level API, public)               │
 │  - Connection, AsyncConnection, HyperProcess        │
@@ -251,7 +251,7 @@ Three *other* crates do define features. `hyperdb-api` is flag-free; the workspa
 
 Tests are organized by crate:
 
-```
+```text
 hyperdb-api/tests/              # Integration tests (high-level API)
 hyperdb-api/tests/common/       # Shared test utilities
 hyperdb-api-core/tests/         # Client-level integration tests
@@ -519,7 +519,7 @@ All commit messages **must** follow the format `<type>(<scope>): <subject>` —
  upstream/main:<path>` and re-lint — rather than assuming, or you will "fix"
  things that were never broken and miss the ones you introduced.
 
- Three traps that have actually bitten:
+ Four traps that have actually bitten:
 
 - **Duplicate `### Fixed` / `### Added` siblings under one `## [Unreleased]`**
  (MD024). Changelogs here often already have the section further down. Merge
@@ -533,6 +533,11 @@ All commit messages **must** follow the format `<type>(<scope>): <subject>` —
  new block. This corrupted 176 fences across 22 files once. Any such pass must
  track fence state; prefer `markdownlint-cli2 --fix`, which is safe, and note
  that it cannot fix MD040 because choosing a language needs judgement.
+- **A nested `.markdownlint.json` replaces the root config rather than merging
+ with it**, so a new one must `extends` the root or every rule there reverts to
+ default. Dropping that line from `docs/superpowers/.markdownlint.json` turns 5
+ findings into 92 — 70 of them the MD060 disabled just below. It hides well: it
+ makes the *linter* wrong, not the document.
 
  Beware format-on-save: a Markdown formatter reformatting tables to satisfy
  MD060 once stripped the README's badge links (`[![CI](img)](target)` became

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,13 +2,13 @@
 
 This page lists the operational governance model of this project, as well as the recommendations and requirements for how to best contribute to Tableau Hyper Rust API. We strive to obey these as best as possible. As always, thanks for contributing – we hope these guidelines make it easier and shed some light on our approach and processes.
 
-# Governance Model
+## Governance Model
 
-## Community Based
+### Community Based
 
 The intent and goal of open sourcing this project is to increase the contributor and user base. The governance model is one where new project leads (`admins`) will be added to the project based on their contributions and efforts, a so-called "do-acracy" or "meritocracy" similar to that used by all Apache Software Foundation projects.
 
-# Issues, requests & ideas
+## Issues, requests & ideas
 
 Use GitHub Issues page to submit issues, enhancement requests and discuss ideas.
 
@@ -40,7 +40,7 @@ Use GitHub Issues page to submit issues, enhancement requests and discuss ideas.
 If you're new to our project and looking for some way to make your first contribution, look for
 Issues labelled `good first contribution`.
 
-# Code Style & Guidelines
+## Code Style & Guidelines
 
 This project follows the **[Microsoft Pragmatic Rust Guidelines](https://microsoft.github.io/rust-guidelines/)**. The repo-specific adaptation — what is machine-enforced, what is reviewer-enforced, and the list of documented exceptions — is in [docs/RUST_GUIDELINES.md](docs/RUST_GUIDELINES.md).
 
@@ -71,7 +71,7 @@ path-filtered, so a docs-only PR does not run it.
 
 When a lint genuinely cannot be satisfied for a given site, suppress it with `#[expect(lint_name, reason = "<specific reason>")]` rather than bare `#[allow(...)]` — the `reason` is mandatory and `#[expect]` auto-removes itself when the lint would no longer fire. See the [Exceptions](docs/RUST_GUIDELINES.md#exceptions) section of the guidelines page for the current workspace-level waivers.
 
-# Contribution Checklist
+## Contribution Checklist
 
 - [ ] Clean, simple, well styled code — conforms to [docs/RUST_GUIDELINES.md](docs/RUST_GUIDELINES.md)
 - [ ] Commits should be atomic and messages must be descriptive. Related issues should be mentioned by Issue number.
@@ -92,7 +92,7 @@ When a lint genuinely cannot be satisfied for a given site, suppress it with `#[
 - [ ] Reviews
   - Changes must be approved via peer code review
 
-# Signed Commits
+## Signed Commits
 
 This repo requires signed commits on `main`. Any PR whose commits are unsigned will be blocked at merge time — the GitHub Actions CI runs fine on unsigned commits, but the merge button won't enable.
 
@@ -129,7 +129,7 @@ Two gotchas to avoid:
 
 GPG signing is also supported — see [GitHub's signing-commits guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) for the GPG and S/MIME paths. SSH is the recommended default for this repo.
 
-# Creating a Pull Request
+## Creating a Pull Request
 
 1. **Ensure the bug/feature was not already reported** by searching on GitHub under Issues. If none exists, create a new issue so that other contributors can keep track of what you are trying to add/fix and offer suggestions (or let you know if there is already an effort in progress).
 2. **Fork** the repository on GitHub.
@@ -142,20 +142,20 @@ GPG signing is also supported — see [GitHub's signing-commits guide](https://d
 
 > **NOTE**: Be sure to [sync your fork](https://help.github.com/articles/syncing-a-fork/) before making a pull request.
 
-# Contributor License Agreement ("CLA")
+## Contributor License Agreement ("CLA")
 
 In order to accept your pull request, we need you to submit a CLA. You only need
 to do this once to work on any of Salesforce's open source projects.
 
 Complete your CLA here: <https://cla.salesforce.com/sign-cla>
 
-# Commit Message Format
+## Commit Message Format
 
 This project uses [Conventional Commits](https://www.conventionalcommits.org/) to automate versioning and release management. Please format your commit messages accordingly.
 
-## Commit Message Structure
+### Commit Message Structure
 
-```
+```text
 <type>(<scope>): <subject>
 
 <body>
@@ -169,7 +169,7 @@ This project uses [Conventional Commits](https://www.conventionalcommits.org/) t
 - **Body** (optional): Detailed explanation of the change
 - **Footer** (optional): Issue references
 
-## Commit Types and Version Impact
+### Commit Types and Version Impact
 
 | Commit Type | Version Bump | Example |
 |------------|--------------|---------|
@@ -182,9 +182,9 @@ This project uses [Conventional Commits](https://www.conventionalcommits.org/) t
 > `fix:` for changes that end-users of the crate or npm package would notice.
 > A `fix(ci):` commit will trigger an unintended patch release.
 
-## Examples
+### Examples
 
-```
+```text
 feat: add support for batch query execution
 
 fix(hyperdb-api-core): resolve type mismatch
@@ -196,13 +196,13 @@ ci: fix chmod step in npm-build-publish workflow
 chore: update arrow dependency to 56
 ```
 
-# Release Process
+## Release Process
 
 This repo uses [release-please](https://github.com/googleapis/release-please)
 to fully automate version bumps, changelog generation, tagging, and the
 crates.io / npm publish dance.
 
-## What contributors do
+### What contributors do
 
 **Use [Conventional Commits](https://www.conventionalcommits.org/) for every
 PR title.** That's it. release-please reads the merged commits to figure out
@@ -219,7 +219,7 @@ The **per-crate** `CHANGELOG.md` files are different: each carries a
 expected to append to them for user-visible API changes. See
 [AGENTS.md](AGENTS.md) reminder 8 for the policy and the full file list.
 
-## What maintainers do
+### What maintainers do
 
 The end-to-end flow lives in
 [`docs/GITHUB_OPERATIONS.md` → Cutting a release](docs/GITHUB_OPERATIONS.md#cutting-a-release).
@@ -250,7 +250,7 @@ For pre-releases (`-rc.N`, `-alpha.N`, `-beta.N`), include a `Release-As:`
 footer in a commit on `main` — see
 [`docs/GITHUB_OPERATIONS.md`](docs/GITHUB_OPERATIONS.md#pre-releases).
 
-## Published Crates
+### Published Crates
 
 | Package | Registry | Notes |
 |---------|----------|-------|
@@ -264,10 +264,10 @@ footer in a commit on `main` — see
 | `hyperdb-compile-check` | crates.io | Compile-time SQL validation backend. Not a workspace member (it declares its own `[workspace]` to break the dependency cycle), but release-please manages its version and it must be published for `hyperdb-api-derive`'s off-by-default `compile-time` feature to resolve. |
 | `hyperdb-api-node` | npm | Node.js/TypeScript bindings. `publish = false` for crates.io — the only crate in the tree that is not a Cargo publish target. |
 
-# Code of Conduct
+## Code of Conduct
 
 Please follow our [Code of Conduct](CODE_OF_CONDUCT.md).
 
-# License
+## License
 
 By contributing your code, you agree to license your contribution under the terms of our project [MIT](LICENSE-MIT) and [Apache-2.0](LICENSE-APACHE) dual license, and to sign the [Salesforce CLA](https://cla.salesforce.com/sign-cla).
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -103,7 +103,7 @@ The API uses **lifetime annotations** to provide compile-time guarantees that re
 are used correctly. All dependent types (`Inserter`, `Catalog`, `Rowset`) carry a `'conn`
 lifetime tying them to their parent `Connection`:
 
-```
+```text
 Connection (owns data)
 ├── Inserter<'conn>
 │   └── CopyInWriter<'conn>
@@ -565,7 +565,7 @@ cargo test -p hyperdb-api --test integration_test
 
 ### Test Structure
 
-```
+```text
 hyperdb-api/tests/           # Integration tests (high-level API)
 hyperdb-api/tests/common/    # Shared test utilities
 hyperdb-api-core/tests/       # Client-level integration tests

diff --git a/README.md b/README.md
@@ -364,8 +364,10 @@ This workspace builds with Red Hat's **system-native Rust toolchain and no
 `rustup`**, which is how enterprise environments typically consume it. RHEL
 provides `rust-toolset` in AppStream as a rolling Application Stream:
 
-    dnf install -y rust-toolset gcc gcc-c++ fontconfig-devel unzip
-    cargo build --release
+```bash
+dnf install -y rust-toolset gcc gcc-c++ fontconfig-devel unzip
+cargo build --release
+```
 
 Notes for system-toolchain builds, all verified against `ubi9/ubi`:
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -1,4 +1,4 @@
-## Security
+# Security
 
 Please report any security issue to [https://www.sfdc.co/SubmitVuln](https://www.sfdc.co/SubmitVuln)
 as soon as it is discovered. This library limits its runtime dependencies in

diff --git a/docs/BENCHMARK_GUIDE.md b/docs/BENCHMARK_GUIDE.md
@@ -17,7 +17,7 @@ specific questions.
 
 All benchmarks share the same schema so numbers compare directly:
 
-```
+```sql
 measurements(id INT NOT NULL, sensor_id INT, value DOUBLE, timestamp BIGINT)
 -- 24 bytes / row
 ```
@@ -145,7 +145,7 @@ block from the suite's stdout.
 
 ### Platform: macOS (Apple Silicon)
 
-**Hardware / software**
+#### Hardware / software
 
 - **OS:** Darwin 26.6.2 (aarch64)
 - **CPU:** Apple M3 Max (14 physical / 14 logical cores)
@@ -301,7 +301,9 @@ unchanged — opt into `ArrowInserter` and `executeQueryColumnar` /
 
 ### Platform: Linux (x86_64)
 
-**Hardware / software** *(placeholder — replace with `host` block from your suite run)*
+#### Hardware / software
+
+*Placeholder — replace with the `host` block from your suite run.*
 
 - **OS:** (e.g. Ubuntu 24.04)
 - **CPU:**
@@ -326,7 +328,7 @@ unchanged — opt into `ArrowInserter` and `executeQueryColumnar` /
 
 ### Platform: Windows (x86_64, native)
 
-**Hardware / software**
+#### Hardware / software
 
 - **OS:** Windows 11 (build 26100) (x86_64)
 - **CPU:** Intel(R) Core(TM) i9-10980XE @ 3.00 GHz (18 physical / 36 logical cores)
@@ -417,7 +419,9 @@ same process.
 
 ### Platform: Windows (x86_64 / WSL2)
 
-**Hardware / software** *(placeholder)*
+#### Hardware / software
+
+*Placeholder — fill in from the `host` block of your suite run.*
 
 - **OS:** (e.g. Ubuntu 22.04 under WSL2)
 - **CPU:**

diff --git a/docs/GITHUB_OPERATIONS.md b/docs/GITHUB_OPERATIONS.md
@@ -51,7 +51,7 @@ the GitHub Release after merging the release PR) or via manual
 `workflow_dispatch` with an explicit tag input (for re-runs or
 emergency releases). Structure:
 
-```
+```text
 verify          ← full test suite + hyperd URL check, single-platform
    │
    └─► publish          ← crates.io publish in dependency order
@@ -104,7 +104,7 @@ without needing Rust toolchains or manual hyperd setup.
 
 **Structure:**
 
-```
+```text
 verify-ci       ← checks that CI passed for this commit (gh api commit status)
    │
    └─► build-npm (matrix × 4 platforms)
@@ -340,7 +340,7 @@ semver: `feat!:` will bump `1.2.3` → `2.0.0` as expected. To stabilize
 the API and cut `1.0.0`, add a `Release-As: 1.0.0` footer to a
 conventional-commit on `main`:
 
-```
+```text
 feat: stabilize public API
 
 Release-As: 1.0.0
@@ -351,7 +351,7 @@ Release-As: 1.0.0
 For an `-rc.N` / `-alpha.N` / `-beta.N` release, add a footer to a
 commit on `main`:
 
-```
+```text
 Release-As: 0.2.0-rc.1
 ```
 

diff --git a/docs/ROW_MAPPING.md b/docs/ROW_MAPPING.md
@@ -8,7 +8,7 @@ struct mapping. Start with the simplest that fits your situation.
 
 All six forms are demonstrated end-to-end in one runnable example:
 
-```
+```bash
 cargo run -p hyperdb-api --example row_mapping_forms
 ```
 

diff --git a/docs/TRANSACTIONS.md b/docs/TRANSACTIONS.md
@@ -28,7 +28,13 @@ txn.commit()?;
 
 #### 1. Exclusive Borrowing
 
-`Connection::transaction(&mut self)` takes a mutable (exclusive) borrow of the connection, and `Transaction<'conn>` holds `&'conn mut Connection`. While the `Transaction` exists, the Rust borrow checker prevents any other code from accessing the raw connection — not even for read-only operations. This eliminates an entire class of bugs where application code accidentally issues SQL statements outside the transaction scope, causing data races or logic errors. The protection is enforced at compile time with zero runtime cost.
+`Connection::transaction(&mut self)` takes a mutable (exclusive) borrow of the
+connection, and `Transaction<'conn>` holds `&'conn mut Connection`. While the
+`Transaction` exists, the Rust borrow checker prevents any other code from
+accessing the raw connection — not even for read-only operations. This
+eliminates an entire class of bugs where application code accidentally issues
+SQL statements outside the transaction scope, causing data races or logic
+errors. The protection is enforced at compile time with zero runtime cost.
 
 ```rust
 let mut conn = Connection::connect(endpoint, "db.hyper", CreateMode::DoNotCreate)?;

diff --git a/docs/superpowers/.markdownlint.json b/docs/superpowers/.markdownlint.json
@@ -0,0 +1,33 @@
+// Directory-scoped rules for docs/superpowers/ (specs and plans).
+//
+// These are point-in-time planning artifacts: a spec and plan are written
+// before a feature, reviewed alongside the change that implements it, and then
+// left alone (AGENTS.md, "Documentation Conventions"). Reflowing prose or
+// re-indenting code blocks in a settled record is churn no reader benefits
+// from, and it is the riskiest place to do it -- these are the longest files in
+// the repo. So the two rules that would force a rewrite are off here:
+//
+//   MD013 line-length     -- plan prose runs to 1500+ characters per line
+//   MD046 code-block-style -- plans mix indented and fenced blocks
+//
+// Every other rule still applies, deliberately. New specs and plans are
+// written all the time, and MD040 (untagged fences) plus the heading rules are
+// the feedback worth having while authoring one. This is a relaxation, not an
+// exclusion: an exclusion would leave the editor silent on a directory that is
+// actively written to.
+//
+// "extends" is load-bearing, not decoration. A nested config REPLACES ancestor
+// configuration rather than merging with it -- verified empirically: without
+// this line, the root's `MD024.siblings_only` reverts to the default and fires
+// on plan files, and `MD060: false` would likewise be lost, re-enabling the
+// rule that was disabled for mangling links. Extending the root config keeps
+// all of it and overrides only the two rules below.
+//
+// Governs both tools from one file: markdownlint-cli2 resolves config per
+// directory, and the VS Code extension walks up from the file being edited
+// (".markdownlint.{jsonc,json,...} file in the same or parent directory").
+{
+  "extends": "../../.markdownlint.json",
+  "MD013": false,
+  "MD046": false
+}
-Original file line number
+Diff line change
@@ Expand Up @@
     All six forms are demonstrated end-to-end in one runnable example:
-    ```
+    ```bash
     cargo run -p hyperdb-api --example row_mapping_forms
     ```
@@ Expand Down @@