Слабые места документации Trip2G и стиль конкурентов

Вопрос исследования

Пользователь попросил:

поискать слабые места документации и порекомендовать правки;
посмотреть у конкурентов, как написаны похожие куски документации, и перенести их стиль/пояснение сюда.

Что было просмотрено в Trip2G docs

Через Trip2G MCP/search были просмотрены ключевые разделы:

• en/user/_index.md — главная документации;
• en/user/getting-started.md — onboarding / first sync;
• en/user/_sidebar.md — структура навигации;
• en/user/advanced.md — custom domains, CLI, SEO;
• en/user/mcp.md — MCP server;
• en/user/federation.md — MCP federation;
• en/user/webhooks.md — change/cron webhooks;
• en/user/default-template.md — default template;
• en/user/frontmatter-patches.md — frontmatter patches;
• en/user/hosting.md — hosting options;
• en/user/use-cases.md — use cases.

Также подзадачами были сопоставлены стили документации конкурентов/аналогов:

• Anthropic MCP / Model Context Protocol;
• Mintlify;
• GitBook;
• ReadMe;
• LlamaIndex;
• LangChain;
• Dify;
• AnythingLLM;
• DocsBot;
• Kapa;
• Zapier;
• Pipedream;
• n8n;
• Stripe webhooks;
• GitHub Actions;
• Clerk/Supabase-style API docs;
• Astro;
• Docusaurus;
• VitePress;
• MkDocs Material;
• Hugo;
• Jekyll.

Главный вывод

Документация Trip2G уже содержит много сильных фич и достаточно конкретики, но её слабость — порядок объяснения.

Сейчас многие страницы выглядят как хороший reference/dev-doc, но для нового пользователя не хватает:

• outcome-first объяснения;
• короткого happy path до концептов;
• “expected result” после каждого setup-шагa;
• verification step;
• recipes/cookbook перед reference;
• troubleshooting рядом с action;
• разделения user docs / advanced docs / dev docs;
• фраз “когда использовать / когда не использовать”.

Лучший общий стиль для Trip2G:

1. Что получится
2. Когда использовать
3. Quickstart / copy-paste path
4. Проверка результата
5. Как это работает
6. Recipes
7. Reference
8. Troubleshooting

Что у Trip2G уже хорошо

Ключевые слабые места

P0. Нет единого “first success” пути

getting-started подробно объясняет установку, но путь всё ещё тяжёлый:

• instance;
• admin login;
• draft versions;
• timezone;
• BRAT;
• plugin;
• API key;
• sync directory;
• _index;
• free: true;
• title.

Это правильно технически, но психологически длинно.

Нужно сильнее оформить начало как:

## Что вы получите за 10 минут

- тестовый vault;
- первая публичная страница;
- подключенный sync;
- понимание, как сделать заметку public/private;
- следующий шаг: MCP или шаблон сайта.

После каждого крупного шага добавить:

Expected result:
- ...

P0. MCP docs нужно подать как retrieval workflow

Сейчас MCP Server начинается хорошо, но дальше быстро уходит в methods/reference.

Конкуренты вроде Anthropic MCP, LlamaIndex, LangChain объясняют через workflow:

Question → search → relevant snippets → open source → answer with citations

Для Trip2G MCP первая страница должна обещать:

После настройки Claude/Cursor/Copilot сможет:

- искать по вашей Trip2G базе;
- открывать релевантные заметки;
- читать только нужные разделы через `toc_path`;
- отвечать со ссылками;
- следовать вашим instructions.

И добавить “Проверьте, что всё работает”:

Спросите агента:

> Search my Trip2G knowledge base for notes about publishing.

Ожидаемо:

- агент вызывает `search`;
- выбирает 2–3 результата;
- вызывает `note_html`;
- отвечает со ссылками на Trip2G pages.

P0. Federation — уникальная фича, но её надо объяснить через “что видит агент”

en/user/federation.md мощный, но сложный.

Главная недостающая секция:

## What the agent sees

Нужно показать:

1. local search находит KB-note;
2. KB-note возвращается с marker kind: federation_kb;
3. agent получает instruction “call federated_search with kb_id”;
4. agent открывает remote note через federated_note_html;
5. answer cites remote source.

Также нужно добавить отдельный блок:

## Writing good KB-notes

Пример хорошей KB-note:

---
mcp_federation_kb_url: https://bob.team.io/_system/mcp
mcp_federation_kb_id: bob
---
Use when: Bob's team decisions, design notes, product status.
Don't use when: personal notes, HR questions, or time-sensitive alerts.
Example questions:
- What did Bob's team decide about API auth?
- Which tradeoffs were discussed for the new editor?

Это стиль Kapa/LangChain: улучшать retrieval quality через качество source descriptions.

P0. Webhooks: нужно сделать API contract, а не только описание фичи

en/user/webhooks.md сильный, но должен быть оформлен как ReadMe/Stripe/Pipedream-style integration docs.

Нужны чёткие разделы:

• Quickstart: create endpoint;
• Setup in admin;
• Payload schema;
• Headers;
• HMAC verification;
• Response contract;
• Safe writes;
• Sync vs async;
• Retries/timeouts;
• Troubleshooting;
• Recipes.

Особенно важно добавить код проверки HMAC:

import crypto from "crypto";

function verifyTrip2GSignature(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

И Python:

import hmac
import hashlib

def verify_trip2g_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Важное предупреждение:

Compute the HMAC from the raw request body bytes, not from parsed JSON. Any key reordering or whitespace changes will break the signature.

P0. expected_hash сейчас потенциально неоднозначен

В webhooks docs сказано, что endpoint может вернуть:

{
  "path": "blog/my-post.md",
  "content": "...",
  "expected_hash": "abc123"
}

и что expected_hash — хеш заметки as received.

Но в user-facing payload example для changes[] не видно поля hash/content_hash, из которого агент должен взять этот expected_hash.

Нужно исправить одно из двух:

1. добавить в payload changes[].hash или changes[].content_hash;
2. или явно объяснить, где получить hash через API.

Рекомендуемая документация:

## Conflict protection: `expected_hash`

`expected_hash` protects against overwriting a note that changed while your service was processing.

Semantics:

- field missing: no conflict check, overwrite allowed;
- `expected_hash: ""`: create-only; fail if file already exists;
- `expected_hash: "abc123"`: update only if current note hash equals `abc123`.

For updates, pass the hash received in the incoming payload:

```json
{
  "path": "blog/post.md",
  "content": "# Corrected post\n\n...",
  "expected_hash": "hash_from_incoming_payload"
}

## P1. Default template слишком большой для первого чтения

`default-template` — один из самых сильных разделов, но он перегружен.

Рекомендуемая структура:

```markdown
# Default template

## Что это даёт
## Quickstart: documentation site layout
## How Trip2G chooses header/footer/sidebar
## Auto-loaded files
## Per-note overrides
## Glob sections
## Content blocks
## Magazine quickstart
## When to use frontmatter patches instead
## Troubleshooting
## Reference

В начало нужно поставить complete minimal example:

Create `_header.md`:

```markdown
![Logo](/logo.png)

- [Home](/)
- [Docs](/docs)
- [Blog](/blog)

Create _left_sidebar.md:

### Getting Started

- [[Getting started]]
- [[Publishing]]

Create docs/_index.md:

---
title: Documentation
content:
  - self
  - magazine
magazine_include_files: "docs/**/*.md"
right_sidebar:
  - TOC
free: true
---
# Documentation

Expected result:

• header appears on all pages;
• sidebar appears;
• docs index shows cards;
• current page has TOC on the right.

## P1. Нужен decision tree: patches vs glob sections vs frontmatter

В Trip2G есть несколько способов делать похожие вещи:

- frontmatter самой заметки;
- auto files `_header.md` / `_footer.md`;
- glob sections;
- frontmatter patches;
- vault-based patches.

Нужно дать “что использовать когда”:

```markdown
## Что использовать?

- Нужна шапка/сайдбар для всего сайта → `_header.md`, `_left_sidebar.md`.
- Нужен сайдбар только для `docs/**` → glob section.
- Нужно массово добавить `free`, `lang`, `layout`, `route` → frontmatter patch.
- Нужно переопределить одну страницу → frontmatter прямо в заметке.
- Нужно хранить правила рядом с контентом и в Git → vault-based patch.

И объяснить разницу:

Glob section не меняет effective frontmatter заметки. Он говорит шаблону: “для этих страниц используй этот sidebar/header/footer”.

Patch меняет effective frontmatter при загрузке. Шаблон видит это так, будто поле было написано в самой заметке.

P1. Frontmatter patches хорошо написаны, но recipes должны идти раньше Jsonnet

Сейчас frontmatter-patches достаточно сильная страница. Её стоит сделать cookbook-first.

В начало:

Frontmatter patch — это “frontmatter по умолчанию” для группы заметок.

Вы пишете правило:
- к каким файлам применить;
- какие поля добавить;
- с каким приоритетом.

Trip2G применяет правило при загрузке. Исходные `.md`-файлы не меняются.

Потом сразу рецепты:

## Make docs public
include: docs/**
expression: { free: true }

## Attach sidebar to docs
include: docs/**
expression: { left_sidebar: "docs/_sidebar.md" }

## Route docs to a subdomain
include: docs/**
expression: { route: "docs.example.com" }

## Do not override custom layout
expression:
if std.objectHas(meta, "layout") then {} else { layout: "default" }

Только потом — meta, path, Jsonnet, priority, vault-based patches.

P1. В docs мало “use this page if”

Для каждой страницы нужно добавить блок:

## Use this page if

Read this page if you want to:

- ...
- ...

Например для Federation:

Use this page if you want one MCP endpoint to search across several Trip2G bases, public knowledge hubs, or private peer instances.

Для Webhooks:

Use this page if you want an external service or AI agent to react when notes change, generate scheduled digests, or write results back to your vault safely.

P2. Много таблиц — лучше bullet reference

Для Telegram/mobile и для markdown-публикации таблицы часто неудобны.

Лучше формат:

- `free`
  - Type: boolean
  - Default: false
  - Purpose: makes a note public.
  - Example: `free: true`

Особенно для:

• MCP tools;
• webhook payload fields;
• frontmatter fields;
• patch fields;
• federation fields.

P2. Нужна отдельная docs information architecture

Текущую навигацию можно усилить так:

Start
- Overview
- Getting started
- Publish your first note
- Concepts

Publish
- Obsidian sync
- Visibility and access
- Default template
- Frontmatter patches
- Custom domains
- Telegram publishing

AI / Agents
- MCP Server
- Instructions
- Federation
- Writing good KB-notes
- Privacy and permissions

Automation
- Webhooks
- Cron jobs
- API tokens
- Recipes

Reference
- Frontmatter fields
- MCP tools
- Webhook payloads
- Jsonnet patches
- CLI
- Environment variables

Troubleshooting
- Sync
- Publishing
- MCP
- Federation
- Webhooks

Важно: AI/MCP нужно выделить как отдельный продуктовый слой, а не прятать в “Reach Your Audience”.

Что именно перенести из стиля конкурентов

Anthropic MCP / MCP official docs

Перенести:

• “What you’ll build”;
• config snippet;
• “Test it”;
• отдельные client-specific guides: Claude Desktop, Claude Code, Cursor;
• Concepts отдельно от Quickstart.

Для Trip2G MCP:

## What you'll build

A Claude/Cursor MCP connection that can search your Trip2G knowledge base and open notes by citation.

Mintlify / GitBook

Перенести:

• короткие страницы;
• cards/callouts/next steps;
• “copy this file”;
• “create first page → add navigation → publish”.

Для default template:

Copy these three files to get a documentation layout:

- `_header.md`
- `_left_sidebar.md`
- `docs/_index.md`

ReadMe / Stripe

Перенести:

• API contract style;
• request/response examples;
• authentication/security section;
• common errors;
• code snippets.

Для webhooks:

Endpoint contract:
- Method: POST
- Content-Type: application/json
- Signature header: X-Webhook-Signature
- Success: 2xx
- Async: 202 Accepted

LlamaIndex / LangChain

Перенести:

• RAG mental model;
• agent loop;
• source/citation workflow;
• “how to improve retrieval quality”.

Для MCP/Federation:

The agent should search first, open only relevant notes, prefer section-level `note_html` with `toc_path`, then answer with citations.

Dify / AnythingLLM / DocsBot / Kapa

Перенести:

• setup in admin UI with expected state;
• workspace/source lifecycle;
• answer quality / citation quality;
• source quality improvements;
• “write good descriptions for sources”.

Для Trip2G:

Improve answer quality:
- split long notes by headings;
- add descriptions;
- write operational instructions;
- describe KB-notes with Use when / Don't use when.

Astro / Docusaurus / VitePress / MkDocs / Hugo / Jekyll

Перенести:

• frontmatter as page config;
• layout as wrapper;
• sidebar/navigation recipes;
• lookup/precedence order;
• cookbook;
• frontmatter reference;
• defaults/cascade model.

Для Trip2G:

Write normal Markdown. Control one page with frontmatter. Control sections with glob sections. Control whole folders with frontmatter patches.

Рекомендуемые первые правки в порядке приоритета

Примеры новых фрагментов для вставки

# MCP Server

Trip2G MCP Server lets Claude, Cursor, GitHub Copilot, Gemini CLI and other MCP clients search your knowledge base and open notes as sources.

## What you'll build

After this guide, your AI client can:

- call `search(query)` across your Trip2G notes;
- open a note or a single section with `note_html`;
- follow your author instructions;
- answer with links to source pages.

## Before you begin

You need:

- a Trip2G instance;
- at least one synced note;
- MCP enabled in site settings;
- an MCP-compatible client.

# Bob's product notes

---
mcp_federation_kb_url: https://bob.example.com/_system/mcp
mcp_federation_kb_id: bob-product
---

Use when: questions about Bob's product decisions, roadmap, design tradeoffs, or customer feedback.

Don't use when: legal, HR, or time-sensitive operational status.

Example questions:
- Why did Bob's team choose SQLite?
- What customer objections came up during onboarding?

## Endpoint contract

Your endpoint must accept:

- Method: `POST`
- Content-Type: `application/json`
- Signature header: `X-Webhook-Signature`

Return:

- `2xx` if the delivery was accepted;
- `401` if signature verification failed;
- `202 Accepted` for async processing;
- JSON body with optional `changes[]` if Trip2G should apply note changes.

Frontmatter patches are defaults for folders.

A patch says:

- which notes it matches;
- which properties it adds;
- when it runs relative to other patches.

Trip2G applies patches at load time. Your markdown files are not modified.

Next steps

1. Сделать отдельную “docs rewrite plan” заметку, где разбить правки на конкретные tasks.
2. Начать с MCP Server, потому что это главный западный developer-facing wedge.
3. Затем Webhooks, потому что там есть риск security/API недопонимания.
4. Затем Federation, потому что это уникальная фича и её нужно сделать понятной на первом экране.
5. Затем default template/frontmatter patches как “Markdown publishing framework”.