vault-scribe

Vault Scribe — навык для превращения расшифровок, видеосводок, заметок встреч, мозговых штурмов, стратегических документов и черновых материалов в аккуратные Markdown-документы, совместимые прежде всего с GitHub Flavored Markdown (GFM). Он особенно полезен при создании заметок для Obsidian, но по умолчанию не добавляет Obsidian-специфические конструкции без явной необходимости: вместо wikilinks предпочитает обычные Markdown-ссылки, чтобы документ оставался читаемым и на GitHub. Навык может быть вызван пользователем и принимает тип заметки вроде article, how-to, technical, meeting, brainstorming, strategy или deep-research; если аргумент не передан, тип выводится из исходного материала. Работа начинается с анализа полного исходника. Навык определяет тему, целевую аудиторию и ключевые понятия, замечает неявную структуру вроде «проблема — решение — примеры» и сохраняет полезные примеры, предупреждения, советы и цитаты. Затем он формирует YAML front matter. Для статьи или справочного материала выбирается article, для пошаговой процедуры — how-to, для архитектуры, RFC и системной спецификации — technical, для исследования с несколькими источниками — deep-research, для версионируемого плана — strategy, для заметок встречи — meeting, а для идей и исследовательского наброска — brainstorming. В front matter должны быть заполнены общие поля и обязательные поля выбранной схемы; полный перечень схем и enum-значений хранится в references/FRONT-MATTER.md и должен быть использован при генерации. Теги оформляются строчными буквами с дефисами, их рекомендуемое количество — от четырёх до восьми; среди них нужен технологический и предметный или концептуальный тег. Основной текст строится как документ с одним H1, совпадающим с title во front matter, и разделами H2/H3. Базовый набор включает обзор предмета, объяснение того, как он работает, практические примеры и ссылки; для подробных материалов целевыми являются также разделы с типичными ошибками, быстрым стартом или чек-листом и дальнейшим чтением. В статьях и руководствах примеры помещаются в fenced code blocks с указанием языка. Для советов, важных понятий, предупреждений, рисков и краткого вывода используются GFM Alerts: NOTE для нейтрального пояснения, TIP для практического совета, IMPORTANT для обязательного к пониманию пункта, WARNING для типичной ошибки и CAUTION для риска потери данных, проблем безопасности или ломающего изменения. Такой формат остаётся читаемым на GitHub и в Obsidian. Навык не вставляет директивы [TOC] или [[_TOC_]]. GitHub и Obsidian умеют строить собственное оглавление, а ручное оглавление добавляется только для длинных документов с шестью и более разделами, когда документ будет читаться вне браузера. Таблицы применяются для сравнений, списков вариантов и справочных данных. В конце обычного документа должна быть таблица ссылок с реальными внешними URL, оформленными как Markdown-ссылки без голых адресов. Документ закрывается callout-блоком [!abstract] с TL;DR. Для callout и синтаксиса Markdown доступны отдельные reference-файлы с правилами, а для изображений, аудио, PDF и других вставок предусмотрены совместимые с GFM и Obsidian варианты. Если исходник содержит расшифровку видео, подкаста, встречи или статьи, Vault Scribe добавляет её после основного документа, отделяя горизонтальной линией и разделом Transcript. В приложении указываются название материала ссылкой, если известен URL, и дата в формате YYYY-MM-DD. Сама расшифровка помещается в fenced code block без языкового идентификатора. Перед добавлением проверяются чувствительные значения: API-ключи и токены распространённых форматов, пароли в URL, DSN с password или pwd, блоки приватных ключей и значения, похожие на секреты, присвоенные полям key, secret, token, password, credential или api_key. Найденные значения заменяются на [REDACTED]; при отсутствии таких шаблонов исходный текст сохраняется. Проверка результата включает валидность YAML, соответствие type выбранной схеме, совпадение title и H1, допустимость category, формат тегов, наличие callout-блоков для советов и предупреждений, fenced-примера для статей и руководств, таблицы ссылок, финального abstract-блока, дат date_created и date_updated и отсутствие голых URL. Для transcript-приложения дополнительно проверяется наличие ссылки на материал, корректной даты и обезличивания чувствительных значений. Навык работает с материалом заметки и Markdown-разметкой; он не заменяет проверку точности внешних фактов, безопасность исполняемого кода или отдельную редакторскую оценку содержания.