Project Instructions

Completion Workflow

After completing each requested change, run the most relevant available validation.
Update the relevant documentation whenever code is changed.
Check the Git working tree and commit the completed changes.
Keep commits scoped to the requested work and do not stage unrelated changes.
Report the commit hash in the final response.
If a change requires restarting a server, application, or other running process before it takes effect, explicitly tell the user what must be restarted.
If a compatibility issue arises, ask the user whether compatibility support is required before proceeding with compatibility-related work.

Do not unconditionally suppress console output or other diagnostic output, including in tests.
Test mocks and diagnostic captures may stay silent by default, but must support MYNOTE_TEST_DIAGNOSTICS=1. When enabled, forward calls with the original receiver, arguments, return value, and output stream intact. Recording output for assertions must continue in both modes.
With diagnostic output enabled, preserve full errors and stacks instead of replacing them with summaries.
Always suppress the standalone libpng iCCP: known incorrect sRGB profile warning, even with diagnostics enabled.
When introducing a new solution that replaces an existing one, ask the user whether to delete the old solution's code. Do not delete it without the user's approval.
Do not delete existing comments, debugging code, logs, or similar development artifacts unless the user explicitly requests their removal.
When extracting code, preserve the original code as much as possible. Do not make unrelated changes or optimizations.

Markdown (.md) files are exempt from all line-count rules in this section. Do not validate or manually count their lines, report them as oversized files, or arrange extraction or splitting solely because of their length.
When extracting modules, prefer on-demand loading when it can be done without changing existing behavior or adding unnecessary complexity.
Prefer to keep individual files under 800 lines. When a file grows beyond that size, consider extracting cohesive modules without changing existing behavior.
If a requested change pushes a file beyond 800 lines, insert the code where it belongs instead of creating a new file solely for that change's code.
In the final report, list files changed by the request that exceed 800 lines, including their final line counts.
Arrange a separate, consolidated module extraction for those files instead of splitting off each change individually.

Add a header comment to each source code file explaining its purpose and main responsibilities.
Add a comment immediately above each function or method definition explaining its purpose.
Separate adjacent function and method definitions with at least one blank line, placed before the next definition's comment.
Do not add comments merely to describe function calls or callback registration. Keep call-site comments only when needed to explain complex logic, non-obvious behavior, or important design decisions.
Comment generated code as thoroughly as practical so its intent, control flow, edge cases, and important assumptions are easy to follow.
At minimum, explain complex logic, non-obvious behavior, and important design decisions.
Avoid comments that only restate the code; keep straightforward comments concise.

When a function takes at most five parameters, prefer separate parameters over an object parameter.
When a function call passes a multiline object argument, put the closing }); on its own line, aligned with the start of the call statement.
Declare only one field per line in interfaces, object type literals (including nested and inline types), and classes.
Expand definitions with multiple fields onto separate lines; do not combine fields with semicolons or commas on one line.
Preserve field names, types, modifiers, optional markers, comments, and runtime behavior when reformatting.

Prefer Flexbox for handling dynamic height and width layouts.
By default, place each single-line form control and its label on the same horizontal row: label on the left, control on the right, vertically centered.
Keep numeric and other short-value controls compact. Allow text controls to use the remaining space without pushing their label onto a separate row.
Apply this layout consistently across settings and dialogs, including new controls. Preserve accessible label associations and prevent horizontal overflow at narrow window widths.
Multiline inputs such as textareas may keep a label above the input. Put help text on a separate line below its field or group.

Do not reuse an element ID as a CSS class name; keep ID and class names distinct to reduce search noise.
Use IDs to identify individual elements and classes to describe reusable styles or roles.
When renaming a class, update its markup, dynamic creation, CSS selectors, and test references together.

Do not use native modal dialogs such as window.alert, window.confirm, or window.prompt; use the application's custom dialog components instead.

Every actionable main-menu item must also be searchable and executable from the command palette.
When adding or changing a main-menu action, register or reuse a command with a stable ID and a clear title.
Route main-menu clicks and command-palette execution through the same command implementation and availability checks.
Verify both entry points and document the command in the relevant FEATURES.md section.

Shortcut modifier names in tooltip text must match the current platform.
- On macOS, display Command or Cmd.
- On Windows and Linux, display Control or Ctrl.
Do not display combined cross-platform placeholders such as Command/Control, Control/Command, Ctrl/Cmd, or Cmd/Ctrl in the rendered tooltip.

Keep README.md focused on the product overview, setup, and primary entry points.
Document detailed feature behavior and interaction rules in the relevant FEATURES.md section instead of expanding the README overview.
When reorganizing documentation, preserve the original content and meaning to the greatest extent possible.
Do not omit documentation details solely to make a document shorter or simpler.
Prefer multiple levels of Markdown headings to organize documentation by topic and subtopic.
- Use any heading level from H1 through H6 when the content calls for it.
- Keep the heading hierarchy consistent.
Break long passages into short, focused sentences, paragraphs, headings, or lists. Do not put hundreds or thousands of characters into a single sentence or list item.
Put multiple distinct pieces of content on separate lines instead of combining them on a single line.
Prefix consecutive lines of distinct content with - so Markdown renders them as separate list items; do not rely on soft line breaks for separation.
Do not continuously append multiple sections or details to a single sentence or list item.
Use nested lists to group related details under a parent topic.
- Put the parent topic on its own list item.
- Put each related detail on its own nested list item.