# Local agent conventions (not committed)

This file is excluded via `.git/info/exclude` and must never be committed or
pushed. It holds conventions for AI agents working in this repo that do not
belong in the public tree.

## Never hard-wrap prose destined for GitHub

GitHub renders a single newline inside a paragraph as a literal `<br>`, not as
reflowable whitespace. This is a GitHub Flavored Markdown deviation from
CommonMark and it applies to every comment field: PR and issue comments, review
summaries, inline review comments, and PR descriptions.

Consequence: prose wrapped at 72 or 80 columns keeps those exact breaks when
rendered, so the text occupies a narrow ragged column and the rest of the
container stays empty. It is worse in inline review comments, which render in a
narrow gutter beside the diff and get wrapped a second time by the browser,
producing a short-long-short-long stagger. Same on mobile.

Rule: one paragraph is one unbroken line. Separate paragraphs with a blank
line. Let the browser wrap.

```
BAD                                   GOOD
The MCP path has no such field,       The MCP path has no such field, only `_meta.authToken`, so this misdirects the reader.
only `_meta.authToken`, so this
misdirects the reader.
```

Hard wrapping is still correct inside fenced code blocks, where the breaks are
meaningful. It is also still correct in the places that genuinely want a fixed
column: commit messages, source comments, and docstrings.

Practical note: when authoring a comment body in a heredoc or shell string, it
is easy to wrap by reflex because the source line looks long. Resist it. If the
body needs to be readable in source, build it as adjacent implicit-concatenated
string literals in a script rather than inserting real newlines.

## Editing already-posted GitHub content

Review bodies use `PUT /repos/{owner}/{repo}/pulls/{pr}/reviews/{review_id}`.
`PATCH` on that path returns 404. Inline review comments use
`PATCH /repos/{owner}/{repo}/pulls/comments/{comment_id}`, keyed on the comment
id, not the review id.

Inline review comments can only be anchored to lines that are part of the diff.
A line outside every hunk is rejected with 422 even though the web UI can reach
it by expanding context. Fold that feedback into the review summary instead, or
add it from the UI after expanding.

## House style for maintainer review comments

Keep the summary to a few sentences stating what blocks the merge; put
specifics on the lines they concern as inline comments. Label blocking versus
non-blocking. Explain why a change is wanted, not only what to change. Avoid
extended praise paragraphs, which read as patronizing; one specific line is
enough. No em dashes anywhere.
