| name | writing-marchat-docs |
| description | Updates marchat documentation and changelogs to match code and release practice. Use when editing CHANGELOG.md, README.md, ARCHITECTURE.md, PROTOCOL.md, TESTING.md, or other project markdown. |
| paths | ["**/*.md"] |
Writing marchat docs
Update docs when behavior, protocol, env vars, or coverage changes. Do not edit markdown the user did not ask for unless required by the same change set.
Style
- Match existing voice: technical, direct, complete sentences.
- Use
**Bold label**: for changelog section prefixes (Client, Server, Docs, Fix:).
- ASCII hyphen
-, not Unicode em dash.
- No decorative emoji in docs or UI chrome descriptions (user message/reaction emoji in product behavior is fine to document).
- Link to
ARCHITECTURE.md, PROTOCOL.md, TESTING.md instead of duplicating long specs.
CHANGELOG.md
- Unreleased on
main only until tag and publish.
- Each release: date, link to prior tag,
git log hint, narrative bullets (not a raw commit dump).
- Call out breaking protocol or keystore changes explicitly.
- Dependency bumps: name and version.
Behavior changes (required)
When user-visible or protocol behavior changes, update CHANGELOG and normative docs together (ARCHITECTURE.md, PROTOCOL.md, TESTING.md, README.md when env/coverage/install facts shift). Update domain skills under .cursor/skills/ when agent workflows or shipped behavior they describe changes. Do not leave CHANGELOG-only updates when other docs or skills would become stale.
README.md
- Install paths, env vars, doctor, DB backends, proxy/WSS, coverage summary pointer to
TESTING.md.
- Keep install script version snippets aligned with latest release when bumping version.
ARCHITECTURE.md / PROTOCOL.md
- Normative for system design and wire JSON shapes.
- E2E: global symmetric ChaCha20-Poly1305; base64 nonce || ciphertext in
content when encrypted is true.
- Do not describe chat E2E as X25519 key exchange.
TESTING.md
- Regenerate coverage with
go test -coverprofile=... and go tool cover -func=....
- Document nested
plugin/sdk separately from main module merge.
- Note doctor
osEnviron / environMu parallel test constraint.
Roadmap
Use ROADMAP.md for planned work. Do not document roadmap items as released unless they exist in code.
Checklist