Reinforce the docstring/comment line-break convention for agents

.github/instructions/docstrings.instructions.md

@@ -35,7 +35,11 @@ def function_name(param1: str, param2: int) -> bool:
 - Use `Example::` (double colon) to introduce a doctest block.
 - Complement type hints — don't duplicate them in the docstring text.
 - Use exactly one space after punctuation (no double spaces after periods).
-- Use line breaks only after punctuation (this facilitates review commenting and text searching). This applies to in-line comments as well, not only docstrings; keep in-line comments short.
+- Use line breaks only after punctuation (this facilitates review commenting and text searching). This applies to in-line comments as well, not only docstrings; keep in-line comments short. So never wrap a docstring or comment in the middle of a phrase; each physical line must end at a comma, semicolon, colon, or period. (E501 is ignored and `max-line-length` is 160, so a long clause on one line is preferred over a mid-phrase break.)
+
+## For code review (incl. automated reviewers)
+
+The line-break-after-punctuation rule above is a deliberate, load-bearing convention (stable review comments and text search), not a stylistic nicety. When reviewing a change, always report a docstring or comment that wraps mid-phrase as a review comment; do not treat such a finding as low-confidence, and do not omit or suppress it.
 
 ## Click CLI commands
 

CLAUDE.md

@@ -0,0 +1,24 @@
+# FlexMeasures — conventions for coding agents
+
+The repo's cross-cutting conventions live in [`.github/instructions/`](.github/instructions/) as
+`*.instructions.md` files (their `applyTo:` frontmatter maps them to file globs). They are written
+for GitHub Copilot, but they are the source of truth for **any** agent working here — read the ones
+relevant to the files you touch, and follow them.
+
+Most-missed rules, called out so they are not forgotten:
+
+- **Docstrings & comments break lines only after punctuation** — never wrap in the middle of a phrase.
+  Each physical line ends at a comma, semicolon, colon, or period. `E501` is ignored and
+  `max-line-length` is 160, so prefer a long clause on one line over a mid-phrase break. This keeps
+  review comments and text search stable. See [`docstrings.instructions.md`](.github/instructions/docstrings.instructions.md).
+- **Run the pre-commit hooks before committing** — they reformat (black), lint (flake8), type-check,
+  and regenerate the OpenAPI spec; a hook that rewrites a file aborts the commit, so re-stage and
+  commit again. See [`pre-commit-hooks.instructions.md`](.github/instructions/pre-commit-hooks.instructions.md).
+- **Add a changelog entry** for user-facing changes, in the right section, with a PR link. See
+  [`changelog.instructions.md`](.github/instructions/changelog.instructions.md).
+- **One logical change per commit** ([`atomic-commits.instructions.md`](.github/instructions/atomic-commits.instructions.md)),
+  **timezone-aware datetimes always** ([`timezone-awareness.instructions.md`](.github/instructions/timezone-awareness.instructions.md)),
+  **catch specific exceptions** ([`error-handling.instructions.md`](.github/instructions/error-handling.instructions.md)),
+  and **"organisation" not "account" in user-facing text** ([`ui-terminology.instructions.md`](.github/instructions/ui-terminology.instructions.md)).
+
+When you add a docstring or comment, re-read it against the line-break rule before moving on.