From eb7c72120e2df8c5c1c22ac6f8e06e30ecc9682c Mon Sep 17 00:00:00 2001
From: Ethan Arrowood <ethan@arrowood.dev>
Date: Thu, 11 Jun 2026 09:18:44 -0600
Subject: [PATCH] docs: require formatting for every contribution in
 AGENTS/CONTRIBUTING

Make `npm run format:write` a hard pre-commit/PR gate rather than
advisory guidance, and clarify it applies to every file in the repo
(not just docs content) so generated scaffolding under plans/, scripts/,
etc. is not missed. Add a dedicated Formatting section to CONTRIBUTING.md
noting CI enforces format:check.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 AGENTS.md       |  3 ++-
 CONTRIBUTING.md | 14 ++++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index a50a847c..920636bb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,7 +14,8 @@ Review `README.md` and `CONTRIBUTING.md` for all relevant repository information
 
 - TypeScript (config files and scripts), MDX/Markdown (content).
 - Prettier is configured via `@harperdb/code-guidelines/prettier` (see `package.json`).
-- Format command: `npm run format:write`. Run this after editing any `.ts`, `.md`, or `.mdx` files.
+- **Required before every commit/PR:** run `npm run format:write`, then confirm `npm run format:check` is clean. This is a hard gate, not advisory — CI fails any unformatted PR (see [CI](#ci)).
+- Formatting applies to **every file in the repo**, not just content. Prettier runs against the whole tree (`prettier .`) — `.ts`, `.md`, `.mdx`, `.json`, and files under `plans/`, `scripts/`, etc. Do not assume a directory is exempt because it is not user-facing docs.
 - The lint script is a no-op (`echo 0`); do not expect `npm run lint` to catch issues.
 
 ## Content Style
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index db09d805..b4c48130 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -30,6 +30,20 @@ npm run format:write
 
 5. Push changes to a branch and create a pull request
 
+## Formatting
+
+**Every contribution must be formatted before it is committed.** This applies to _all_ files in the repository — content (`.md`/`.mdx`), TypeScript, config, and anything else under `plans/`, `scripts/`, etc. — not just docs content.
+
+```bash
+# Format everything (run before committing):
+npm run format:write
+
+# Check formatting without writing (what CI runs):
+npm run format:check
+```
+
+CI runs `npm run format:check` on every pull request and will fail if anything is unformatted. If CI fails on formatting, run `npm run format:write` locally and commit the result. Prettier is configured via `@harperdb/code-guidelines/prettier` (see `package.json`).
+
 ## Site Organization
 
 This site is powered by Docusaurus. The documentation is split into four distinct sections, each serving a different purpose and configured as its own Docusaurus plugin instance.