Update formatting of agent rules documentation

[Stanzilla]

Markdown documents should only have one h1 header, it is pretty unlikely that an existing agents config does not already have one, switching to h2 instead should make most linters happy.

In theory you could make this a little smarter by checking beforehand..

I am also considering adding a line akin to

Never use `nx graph` command - This spawns a web server that you don't have access to. 
Use the `nx_visualize_graph` tool or other nx tools instead.

since mine keeps doing that. thoughts?

Current Behavior

The header is inserted as an h1

Expected Behavior

The header is inserted as an h2

Related Issue(s)

Fixes #

[netlify]

👷 Deploy request for nx-docs pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	3cc4688

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
nx-dev	Ready	Preview	Nov 3, 2025 10:37pm

[MaxKless]

I see what you mean... we decided for an h1 originally because then we can make sure that we're not messing with anyone's layout by nesting something where they don't want to.
I wasn't aware of this best practice to only ever use one h1 though, what kind of markdown linter are you using? Does it have that preconfigured?
I'm open to changing this in general though.

[Stanzilla]

I see what you mean... we decided for an h1 originally because then we can make sure that we're not messing with anyone's layout by nesting something where they don't want to. I wasn't aware of this best practice to only ever use one h1 though, what kind of markdown linter are you using? Does it have that preconfigured? I'm open to changing this in general though.

I'm on https://github.com/DavidAnson/markdownlint-cli2 (or rather the tooling around it) the rule is https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md025.md

[Stanzilla]

there are also spacing issues, currently it has two blank links before and after the snippet, which also triggers linters. so if we want to make it smarter it should

• check if it is the only content of the file, if yes, no space before, use an h1 and then 1 or 0 empty lines after
• if it is not the only content, use h2 with one space before and one after