ai(rules[AGENTS{docs}]): Add Changelog Conventions section

why: vcspull's CHANGES has historically used a flatter
`### Section` + `-` bullet shape than its sister libraries
(libtmux, tmuxp, libvcs), all of which use Django-style
`#### Title (#NN)` subsections with prose bodies. The shape
divergence makes the family of release notes harder to scan
across projects. Codify the Django shape for new entries while
leaving historical entries intact — older entries continue to
read as they were written; new ones converge on the family
standard.

what:
- New "Changelog Conventions" sub-section under "Documentation
  Standards" (after "Shell Command Formatting").
- Notes the `vX.Y.Z` version prefix specific to vcspull.
- Same rule set as the sister projects: release entry boilerplate,
  multi-sentence lead paragraph with version-as-subject,
  deliverable-as-section (`#### Title (#NN)` shape), the
  deliverable test, fixed subheading order, PR refs in headings,
  when bullets are appropriate, anti-patterns, always-link
  autodoc'd APIs, MyST role table, summarization style.
- Explicit transition note in the intro: older flat-bullet
  entries stay as-is; the rules govern new entries.

Author: tony

AGENTS.md

@@ -485,6 +485,37 @@ Bad:
 $ vcspull import gh my-org --mode org -w ~/code/
 ```
 
+### Changelog Conventions
+
+These rules apply when authoring entries in `CHANGES`, which is rendered as the Sphinx changelog page. Modeled on Django's release-notes shape — deliverables get titles and prose, not bullets. Older entries used a flat `### Section` + bullet shape; new entries follow the Django shape below.
+
+**Release entry boilerplate.** Every release header is `## vcspull vX.Y.Z (YYYY-MM-DD)` (note the `v` prefix on the version). The file opens with a `## vcspull vX.Y.Z (unreleased)` placeholder block fenced by `<!-- KEEP THIS PLACEHOLDER ... -->` and `<!-- END PLACEHOLDER ... -->` HTML comments — new release entries land immediately below the END marker, never above it.
+
+**Open with a multi-sentence lead paragraph.** Plain prose, no italic. Open with the version as sentence subject (*"vcspull vX.Y.Z ships …"*) so the lead is self-contained when excerpted. Two to four sentences telling the reader what shipped and who cares — user-visible takeaways, not internal mechanism. Cross-reference detail docs with `{ref}` to keep the lead compact.
+
+**Each deliverable is a section, not a bullet.** Inside `### What's new`, every distinct deliverable gets a `#### Deliverable title (#NN)` heading naming it in user vocabulary, followed by 1-3 prose paragraphs explaining what shipped. Don't wrap a paragraph in `- ` — bullets are for enumerable lists, not paragraph containers. Cross-link detail docs (`See {ref}\`foo\` for details.`) so prose stays focused.
+
+**The deliverable test.** Before writing an entry, ask: "What's the deliverable, in user vocabulary?" If you can't answer in one sentence, the entry isn't ready. Mechanism (helper internals, byte counters, schema-validation locations) belongs in PR descriptions and code comments, not the changelog.
+
+**Fixed subheadings**, in this order when present: `### Breaking changes`, `### Dependencies`, `### What's new`, `### Fixes`, `### Documentation`, `### Development`. Dev tooling (helper scripts, internal automation) lives under `### Development`. For breaking changes, show the migration path with concrete inline code (e.g. a `# Before` / `# After` fenced code block). Dependency floor bumps use the form ``Minimum `pkg>=X.Y.Z` (was `>=X.Y.W`)``.
+
+**PR refs `(#NN)`** sit in each deliverable's `####` heading.
+
+**When bullets are appropriate.** Catch-all sections (`### Fixes`, occasionally `### Documentation`) with 3+ genuinely small items use bullets — one line each, never paragraphs. If a bullet swells past two lines, promote it to a `#### Title (#NN)` heading with prose body.
+
+**Anti-patterns.**
+
+- Fragile metrics: token ceilings, third-party version pins, percent benchmarks, exact byte counts. Describe the *capability*, not the math.
+- Internal jargon: private symbols (leading-underscore identifiers), algorithm names exposed for the first time, backend scaffolding.
+- Walls of text dressed up as bullets.
+- Buried breaking changes — they get their own subheading at the top of the entry.
+
+**Always link autodoc'd APIs.** Any class, method, function, exception, or attribute that has its own rendered page must be cited via the appropriate role (`{class}`, `{meth}`, `{func}`, `{exc}`, `{attr}`) — never with plain backticks. Doc pages without explicit ref labels use `{doc}`. Plain backticks are correct for code syntax, env vars, parameter names, and file paths that aren't doc pages — anything without an autodoc destination.
+
+**MyST roles.** Class references use `{class}` (e.g. `{class}\`~vcspull.config.ConfigReader\``), methods use `{meth}`, functions use `{func}`, exceptions use `{exc}`, attributes use `{attr}`, internal anchors use `{ref}`, doc-path links use `{doc}`.
+
+**Summarization style.** When a user asks "what changed in the latest version?" or similar, lead with the entry's lead paragraph (paraphrased if needed), followed by each `####` deliverable heading under `### What's new` with a one-sentence summary. Cite `(#NN)` only if the user asks for source links. Don't invent versions, dates, or numbers not present in `CHANGES`. Don't quote line numbers or file offsets — those shift as the file evolves.
+
 ## Debugging Tips
 
 When stuck in debugging loops: