docs

Write comments that explain why the code exists, not what it does, since the code already shows what. Use sentence case with one space after the comment marker, keep comments close to the code they describe, and delete stale comments when code changes.

A JSDoc block should include a one-line summary, an @param tag for every parameter with type and description, @returns with type and description, @throws for each error condition, and @example for non-obvious usage. Omit JSDoc for trivial private helpers and self-evident getters.

No, emojis are never allowed in code files, inline comments, JSDoc, or TODO notes. They are acceptable in markdown files like READMEs and changelogs. Existing emojis in source files should be replaced with plain text labels like Note: or Warning:.

Use version headers with dates like ## [1.2.0] - 2026-04-17, then group entries under Added, Changed, Deprecated, Removed, Fixed, and Security sections. Each entry is a concise bullet describing the change.

A README should contain a one-paragraph summary, deployment instructions with exact commands split into Pre, Deploy, and Post steps, freeform operator notes, open tasks, and known issues. Write for someone on-call who has never seen the project.