ТЗ для агента: переписать документацию Trip2G по пирамиде Минто

1. Использовать пирамиду Минто

Каждая страница должна отвечать сверху вниз:

Главный тезис страницы
├─ Что пользователь получит
├─ Как это сделать минимальным путём
├─ Как проверить успех
└─ Какие детали нужны дальше

Не начинать с внутренней архитектуры, терминов или полного reference.

2. Добавлять “Expected result” после действий

После каждого setup-блока:

Expected result:

- ...

или:

Проверьте:

- ...

3. Добавлять “Use this page if”

В начале каждой страницы:

## Use this page if

Read this page if you want to:

- ...
- ...

4. Reference держать ниже recipes

Сначала показать:

• минимальный рабочий пример;
• 2–4 типовых рецепта;
• troubleshooting.

Только потом полный список полей, методов, параметров.

5. Не использовать большие markdown-таблицы как основной формат

В Trip2G/Telegram/мобильном чтении таблицы неудобны. Поля лучше писать bullet-reference:

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

6. Явно отделять user docs от dev/internal docs

В user docs избегать:

• Ctx struct;
• internal render pipeline;
• implementation details;
• термины без сценария.

В user docs писать:

• “Создайте файл...”;
• “Добавьте frontmatter...”;
• “Trip2G автоматически...”;
• “Результат: ...”.

Главный вывод страницы

Trip2G MCP Server позволяет Claude, Cursor, GitHub Copilot, Gemini CLI и другим MCP-клиентам искать по базе Trip2G, открывать заметки/разделы и отвечать со ссылками на источники.

Почему это P0

Это главный developer-facing западный wedge:

Make your docs / vault agent-readable.

Если MCP docs понятны, Trip2G проще продвигать как docs-to-MCP и Obsidian-to-MCP продукт.

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

# MCP Server

## What you'll build
## Use this page if
## Before you begin
## Quickstart
### 1. Publish at least one note
### 2. Create an instructions note
### 3. Enable MCP in settings
### 4. Connect an MCP client
### 5. Ask a test question
## How retrieval works
## Available tools
## Token-saving with `toc_path`
## Improve answer quality
## Privacy
## Troubleshooting
## Next steps

Вставить начало страницы

# 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.

## Use this page if

Read this page if you want to:

- use Trip2G as memory for Claude, Cursor or another MCP client;
- make Markdown/Obsidian/docs searchable by agents;
- build an expert knowledge base that answers with citations.

Добавить retrieval workflow

## How retrieval works

```text
User question
  ↓
AI client calls `search(query)`
  ↓
Trip2G searches synced notes
  ↓
Search results return snippets, URLs and TOC paths
  ↓
AI client calls `note_html(...)`
  ↓
AI answers with citations

### Добавить verification

```markdown
## Verify it works

Ask your agent:

> Search my Trip2G knowledge base for notes about publishing.

Expected result:

- the agent calls `search`;
- it finds 2–5 relevant notes;
- it calls `note_html` for the strongest source;
- the answer includes links to Trip2G pages.

Добавить Improve answer quality

## Improve answer quality

- Give notes clear titles.
- Use headings in long notes.
- Add `description` to important pages.
- Keep the instructions note short and operational.
- Split unrelated topics into separate notes.
- Use `toc_path` for long pages.

Главный вывод страницы

Webhooks — это безопасный способ запускать внешние сервисы и AI-агентов при изменениях заметок или по расписанию, включая ограниченные временные токены, подписи HMAC, безопасную запись результатов и защиту от конфликтов.

Почему это P0

Webhooks содержат security-sensitive фичи:

• HMAC signatures;
• temporary API tokens;
• write_patterns;
• expected_hash;
• sync/async responses;
• recursion depth.

Их нельзя объяснять как “просто фичу”; это должен быть API contract.

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

# Webhooks and Cron

## What you'll build
## Use this page if
## Two webhook types
## Quickstart: change webhook
## Quickstart: cron webhook
## Endpoint contract
## Payload schema
## Verify HMAC signature
## Temporary API token
## Response contract
## Safe writes and `expected_hash`
## Sync vs async
## Recursion protection
## Recipes
## Troubleshooting

Добавить endpoint contract

## 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.

Добавить HMAC examples

Node.js:

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.

Уточнить expected_hash

Проверить реализацию. Если входной payload уже содержит hash — документировать его. Если нет — завести issue/product task.

Документация должна объяснять:

## 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 or read through the API.

Добавить sync vs async decision guide

Use sync when:

- the task finishes within the timeout;
- you can return changes immediately;
- the task updates a small number of notes.

Use async when:

- the task may take more than 60 seconds;
- an AI model or external API is slow;
- the task needs many API calls;
- the result can be applied later.

Добавить recipes

Минимум:

• AI spelling/grammar linter;
• daily digest;
• weekly report;
• external search index updater;
• Slack/Discord notification;
• SEO metadata agent.

Главный вывод страницы

MCP Federation позволяет одному Trip2G hub искать по нескольким knowledge bases через один MCP endpoint, без копирования remote content.

Почему это P0

Это уникальная фича Trip2G. Её нужно объяснить как “agent routing”, а не как сложную сеть.

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

# MCP Federation

## What you'll build
## Use this page if
## Mental model
## Quickstart: add a public peer
## Quickstart: add a private peer
## What the agent sees
## Writing good KB-notes
## Federation tools
## Permissions
## Limits
## Troubleshooting

Добавить mental model

## Mental model

```text
AI client
  ↓ one MCP endpoint
Your Trip2G hub
  ├─ local notes
  ├─ public KB
  ├─ private peer KB
  └─ external adapter KB

Your hub does not copy remote content. It stores:

• your notes;
• KB-notes with peer URLs;
• federation secrets for private peers.

### Добавить what the agent sees

```markdown
## What the agent sees

When local `search` returns a KB-note, the result tells the agent which remote base to query next.

Recommended workflow:

1. Call `search(query)`.
2. If a KB-note is relevant, call `federated_search(query, kb_id)`.
3. Open the best remote result with `federated_note_html`.
4. Cite the remote source URL.

Добавить good KB-note example

---
title: 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?

Главный вывод страницы

Default template — это built-in layout framework для markdown-сайта: header, footer, sidebars, TOC, backlinks, related notes, magazine grid — без HTML, через markdown и frontmatter.

Почему это P1

Это одна из самых сильных фич Trip2G как publishing framework, но текущая страница слишком большая и reference-heavy.

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

# Default template

## What you'll build
## Use this page if
## Quickstart: documentation 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

## Quickstart: documentation layout

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.

### Добавить decision tree

```markdown
## What should I use?

- Need a header/sidebar for the whole site → `_header.md`, `_left_sidebar.md`.
- Need a sidebar only for `docs/**` → glob section.
- Need to mass-add `free`, `lang`, `layout`, `route` → frontmatter patch.
- Need to override one page → frontmatter on that note.
- Need rules versioned with content → vault-based patch.

Главный вывод страницы

Frontmatter patches — это “frontmatter по умолчанию” для группы заметок. Они применяются при загрузке и не меняют исходные markdown-файлы.

Почему это P1

Страница уже хорошая, но должна стать cookbook-first: сначала задачи, потом Jsonnet/reference.

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

# Frontmatter patches

## What you'll build
## Use this page if
## Mental model
## Quickstart: make a folder public
## Common recipes
## How patches work
## Admin patches vs vault patches
## Jsonnet basics
## Priority and conflicts
## Troubleshooting
## Reference

Добавить mental model

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.

Добавить patch → effective frontmatter examples

Patch:

```jsonnet
{ free: true }

Effective frontmatter:

---
free: true
---

The source file stays unchanged.

### Добавить recipes раньше Jsonnet

```markdown
## Recipes

### Make docs public

Include: `docs/**`
Expression:

```jsonnet
{ 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

if std.objectHas(meta, "layout")
then {}
else { layout: "default" }

## Task 6 — улучшить `en/user/getting-started.md`

### Главный вывод страницы

Getting Started должен вести пользователя к первому публичному результату, а не просто перечислять необходимые настройки.

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

```markdown
# Getting started

## What you'll build
## Before you begin
## Safety note: use a test vault
## 1. Sign in
## 2. Enable draft preview
## 3. Install the Obsidian plugin
## 4. Create an API key
## 5. Connect the plugin
## 6. Publish your first page
## 7. Make it public
## Verify
## Troubleshooting
## Next steps

Добавить верхний summary

## What you'll build

In about 10 minutes, you will:

- create a test Obsidian vault;
- connect it to Trip2G;
- publish your first page;
- make it public;
- understand how private/public notes work.

Сделать safety note заметнее

> Safety note
> Start with a separate test vault. The plugin uploads files from the configured folder. Do not connect a personal vault until you understand what will sync.

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

AI/Agents и Automation должны быть отдельными продуктовым слоями в навигации, а не скрываться рядом с publishing/Telegram.

Предложенная IA

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