docs: update documentation for v5.9 (#876)

Author: antonreshetov

.agents/skills/documentation-workflow/SKILL.md

@@ -25,12 +25,38 @@ description: Use when adding or updating massCode documentation, documenting a n
 - Пользовательская документация сайта пишется на английском, в стиле существующих docs pages.
 - Добавляй или обновляй наиболее конкретную страницу в `docs/website/documentation`.
 - Для новых страниц используй frontmatter с `title` и `description`.
-- Если фича доступна только с конкретного релиза, добавляй `<AppVersion text=">=x.y" />` ближе к началу страницы.
 - Добавляй страницу в `docs/website/.vitepress/config.mts` только если она должна появиться в навигации.
 - Ссылайся из `docs/website/documentation/index.md` только на широкие, cross-cutting фичи.
 - Пиши короткими task-oriented секциями. Предпочитай пользовательские флоу, а не детали реализации.
 - Shortcuts документируй через `<kbd>...</kbd>` и указывай macOS плюс Windows/Linux варианты, если они отличаются.
 
+## Version Availability
+
+- Перед добавлением или изменением `<AppVersion>` проверяй историю фичи в коде, документации или предыдущем релизном теге.
+- Считай `<AppVersion text=">=x.y" />` минимальной версией, где появилась ровно описываемая возможность, а не версией её последнего улучшения.
+- Ставь marker на уровне страницы или общего раздела только когда вся описываемая сущность впервые появилась в этой версии.
+- Если новый релиз расширяет существующую фичу, сохраняй её исходный marker или отсутствие marker, а новую версию указывай только у отдельного подпункта или предложения про улучшение.
+- Разделяй смешанное описание на базовую возможность и versioned enhancement, если общий marker создаёт впечатление, что старая возможность раньше была недоступна.
+- Не добавляй version marker для bugfix или внутренней переработки без нового пользовательского сценария. Локально отмечай изменение формата хранения, если оно влияет на совместимость.
+
+Пример: если custom folder icons существуют с 3.7, а Emoji и Upload добавлены в 5.9, оставляй `>=3.7` у базовой возможности и ставь `>=5.9` только у подпункта про Emoji и Upload.
+
+## Documentation Weight
+
+- Перед созданием страницы или раздела оцени самостоятельность пользовательского сценария, количество шагов, настроек и ограничений.
+- Описывай мелкое одношаговое действие одной строкой или буллетом внутри существующего релевантного раздела.
+- Создавай отдельный раздел для самостоятельного workflow с несколькими шагами, вариантами, настройками или важными ограничениями.
+- Выбирай одно основное место для подробного описания cross-cutting фичи. В других страницах оставляй короткое упоминание или ссылку вместо повторения полного объяснения.
+- Оставляй bugfix, внутреннюю оптимизацию и implementation detail только в release notes, если они не меняют пользовательский сценарий или требования совместимости.
+
+## Callouts
+
+- Используй `warning` для риска потери данных, несовместимости, необратимого действия или существенного security-ограничения.
+- Используй `info` для автоматической миграции и неочевидного поведения, которое помогает правильно понять основной workflow.
+- Оставляй основные инструкции обычным текстом; callout должен выделять контекст или исключение, а не содержать весь сценарий.
+- Объединяй связанные риски в один callout и избегай нескольких соседних блоков, если их можно прочитать как одно сообщение.
+- Добавляй короткий предметный заголовок, например `::: warning Compatibility` или `::: info Automatic migration`.
+
 ## VitePress Markdown Gotchas
 
 - VitePress компилирует markdown как Vue-компонент, поэтому `{{ ... }}` трактуется как Vue-интерполяция и **исчезает** из вывода.
@@ -67,6 +93,10 @@ description: Use when adding or updating massCode documentation, documenting a n
 - Добавлять README-only документацию для фичи, которой нужна настоящая docs page.
 - Забывать VitePress sidebar для новой страницы, которая должна быть в навигации.
 - Добавлять version availability в README.
+- Переносить `<AppVersion>` всего существующего раздела на версию, в которой фича лишь получила улучшение.
+- Создавать отдельный раздел для одношаговой мелкой фичи, которую достаточно упомянуть в существующем разделе.
+- Повторять полное описание cross-cutting фичи на нескольких страницах вместо одного основного места и коротких упоминаний.
+- Использовать callout для обычной инструкции без риска, совместимости или неочевидного поведения.
 - Документировать shortcuts или поведение без проверки реализации.
 - Запускать широкие formatters, которые переписывают существующий стиль docs config.
 - Писать литеральные `{{ ... }}` в инлайн-коде без `v-pre` — VitePress съест их как Vue-интерполяцию.

README.md

@@ -138,7 +138,7 @@ Sketch diagrams, wireframes, and whiteboard ideas on an [Excalidraw](https://exc
 Built-in utilities for the small tasks that usually send you to a browser tab:
 
 - **Compare:** JSON Diff
-- **Text:** Case Converter, Slug Generator, URL Parser
+- **Text:** Case Converter, Slug Generator, URL Parser, Line Break Normalizer
 - **Crypto:** Hash/HMAC Generator, Password Generator, UUID
 - **Encoders:** URL, Base64, JSON to TOML/XML/YAML, Color Converter
 - **Generators:** JSON Generator, Lorem Ipsum

docs/website/.vitepress/config.mts

@@ -141,7 +141,7 @@ export default defineConfig({
             { text: 'Sync', link: '/documentation/sync' },
             { text: 'Imports', link: '/documentation/imports' },
             { text: 'Clipper', link: '/documentation/clipper' },
-            { text: 'Themes', link: '/documentation/themes' },
+            { text: 'Appearance', link: '/documentation/themes' },
           ],
         },
         {

docs/website/documentation/code/folders.md

@@ -35,14 +35,21 @@ Right-click the folder and choose **"Default Language"**.
 
 ## Setting a Folder Icon
 
+<AppVersion text=">=3.7" />
+
+Folder icons help large libraries stay easier to scan. Right-click a folder and choose **Set Icon**. Use the **Icons** tab to search the built-in Material and Lucide icon collections.
+
+To restore the default folder icon, right-click the folder and choose **Remove Icon**.
+
+### Emoji and Uploaded Images
+
 <AppVersion text=">=5.9" />
 
-Folder icons help large libraries stay easier to scan. Right-click a folder and choose **Set Icon**, then select one of these tabs:
+The icon picker also supports:
 
 - **Emoji** - search the Unicode emoji catalog. Emoji appearance follows your operating system.
-- **Icons** - search the built-in Material and Lucide icon collections.
 - **Upload** - choose or drop a JPG or PNG image up to 10 MB, review the preview, then click **Use image**.
 
-Uploaded images are cropped from the center, resized to 128×128, and saved as PNG. To restore the default folder icon, right-click the folder and choose **Remove Icon**.
+Uploaded images are cropped from the center, resized to 128×128, and saved as PNG.
 
 Uploaded icons are stored as a hidden `.icon.png` file inside the folder, so they stay with the folder when you back up or sync your Markdown Vault.

docs/website/documentation/code/snippets.md

@@ -67,6 +67,8 @@ Use one of these methods:
 - XML
 - YAML
 
+Use **Editor** > **Normalize Line Breaks** to remove hard terminal wraps from the selection or the whole snippet. <AppVersion text=">=5.9" />
+
 ## Real-time Render HTML & CSS
 
 <AppVersion text=">=2.9" />

docs/website/documentation/command-palette.md

@@ -68,7 +68,9 @@ When create fallbacks are shown, press <kbd>Shift+Enter</kbd> to run the first c
 
 Open the actions panel for the selected result with <kbd>Right Arrow</kbd> or <kbd>Cmd+K</kbd> on macOS and <kbd>Ctrl+K</kbd> on Windows and Linux.
 
-Actions depend on the selected result. For example, you can copy a title, copy snippet content, copy an HTTP request URL, or run the selected command.
+Actions depend on the selected result. For example, you can copy a title, copy snippet content, duplicate a snippet or HTTP request, copy an HTTP request URL, or run the selected command.
+
+You can also duplicate a note while preserving its content, description, properties, and tags. <AppVersion text=">=5.9" />
 
 Use <kbd>Left Arrow</kbd> or <kbd>Esc</kbd> to close the actions panel.
 

docs/website/documentation/http/index.md

@@ -42,9 +42,13 @@ Importing creates HTTP folders, requests, and environments from external collect
 
 HTTP requests are organized in folders. Selecting a folder shows its requests and selects the first request in that folder. Folders support nesting, drag and drop ordering, inline rename, and custom folder icons.
 
+Right-click a folder and choose **Set Icon** to select a built-in Material or Lucide icon. Choose **Remove Icon** to restore the default folder icon.
+
+### Emoji and Uploaded Images
+
 <AppVersion text=">=5.9" />
 
-Right-click a folder and choose **Set Icon** to select a platform-native emoji, a built-in Material or Lucide icon, or an uploaded JPG or PNG image. Uploaded images can be previewed before applying and are cropped from the center and resized to 128×128. Choose **Remove Icon** to restore the default folder icon.
+The icon picker also supports platform-native emoji and uploaded JPG or PNG images. Uploaded images can be previewed before applying and are cropped from the center and resized to 128×128.
 
 ## Storage
 

docs/website/documentation/notes/folders.md

@@ -23,15 +23,18 @@ Right-click the folder and choose **"Rename"** or **"Delete"**.
 
 ## Folder Icons
 
-<AppVersion text=">=5.9" />
-
 Folder icons make larger note libraries easier to scan. Right-click a folder and choose **Set Icon**.
 
+Use the **Icons** tab to search the built-in Material and Lucide collections. Choose **Remove Icon** from the folder context menu to restore the default icon.
+
+### Emoji and Uploaded Images
+
+<AppVersion text=">=5.9" />
+
 - **Emoji** uses the system emoji style for your platform.
-- **Icons** provides searchable Material and Lucide collections.
 - **Upload** accepts JPG or PNG images up to 10 MB and shows a preview before applying the image.
 
-Uploaded images are cropped from the center, resized to 128×128, and stored as a hidden `.icon.png` file inside the folder. Choose **Remove Icon** from the folder context menu to restore the default icon.
+Uploaded images are cropped from the center, resized to 128×128, and stored as a hidden `.icon.png` file inside the folder.
 
 ## Moving Notes
 

docs/website/documentation/notes/images.md

@@ -7,7 +7,7 @@ description: "Embed images in massCode Notes with standard markdown syntax, past
 
 Use images when a screenshot, diagram, or visual reference belongs next to the note text.
 
-Images are rendered directly inside your note from standard markdown image syntax. For local images, paste an image from the clipboard or drag an image file into the editor. massCode saves new files to `notes/.masscode/assets` in your vault and inserts the markdown for you.
+Images are rendered directly inside your note from standard markdown image syntax. For local images, paste an image from the clipboard or drag an image file into the editor. massCode stores the file in the vault and inserts the markdown for you.
 
 ```md
 ![image-name](masscode://notes-asset/generated-file-name.png)
@@ -19,9 +19,21 @@ You can also use a remote image URL:
 ![Remote screenshot](https://example.com/screenshot.png)
 ```
 
-The `masscode://notes-asset/` URL is resolved by massCode. Other Markdown apps may not display these local images directly. When you copy or synchronize Notes between devices, include the whole vault, including the hidden `notes/.masscode` directory. Copying only Markdown files leaves their local images behind.
+The `masscode://notes-asset/` URL is resolved by massCode. Other Markdown apps may not display these local images directly.
 
+## Managed Storage
+
+<AppVersion text=">=5.9" />
+
+Starting with massCode 5.9, newly pasted or dropped images are saved to `notes/.masscode/assets`. When you copy or synchronize Notes between devices, include the whole vault, including the hidden `notes/.masscode` directory. Copying only Markdown files leaves their local images behind.
+
+::: warning Compatibility
 Vaults with images in the managed `notes/.masscode/assets` path require a massCode version that supports this layout. Older versions may not display these images.
+:::
+
+::: info Automatic migration
+When a note references an image from the legacy `notes/assets` directory, massCode migrates that referenced file to managed storage and updates the note automatically. Unreferenced files are left in place.
+:::
 
 - Paste or drag images in **Editor** and **Live Preview** modes.
 - View images in **Live Preview** or **Preview** mode.

docs/website/documentation/notes/index.md

@@ -30,6 +30,8 @@ Use Notes when you want to keep markdown documents close to your snippets and da
 
 See [Tasks](/documentation/notes/tasks) to create task notes with structured status, priority, and due date properties.
 
+To duplicate an existing note, right-click it in the Notes list and choose **Duplicate**. The copy stays in the same folder and its title is selected for renaming. <AppVersion text=">=5.9" />
+
 ## Dashboard
 
 <AppVersion text=">=5.1" />
@@ -62,6 +64,8 @@ The editor is built on CodeMirror 6 and includes:
 - Right-click formatting menu in editable modes
 - Inline markdown formatting shortcuts in editable modes
 - Editable markdown tables in Live Preview
+- One-click copying for fenced code blocks in Live Preview and Preview <AppVersion text=">=5.9" />
+- Line break normalization for hard-wrapped terminal text from **Editor** > **Normalize Line Breaks** <AppVersion text=">=5.9" />
 - [Internal links](/documentation/notes/internal-links) to notes and snippets
 - [Task notes](/documentation/notes/tasks) with status, priority, due dates, and smart views
 - [Mermaid diagram](/documentation/notes/mermaid) support
@@ -117,6 +121,7 @@ Customize the editor appearance and behavior in preferences:
 - **Indent size**
 - **Limit width** - toggle to constrain the editor width
 - **Line numbers** - toggle to show or hide line numbers
+- **Wrap table cells** - wrap long cell content so wide tables stay within the editor <AppVersion text=">=5.9" />
 
 <script setup>
 import { withBase } from 'vitepress'