User Docs — Mermaid Diagrams Plan

Goal

Add Mermaid diagrams to the highest-value user-doc pages. The analysis kept 29 diagrams (20 high, 9 medium) out of 80 raw ideas — dropping decorative two-node flows and comparisons that are better as Markdown tables. Ready-to-paste, syntax-checked code for every kept diagram is in § Diagrams below.

Conventions

• Mermaid renders inside ```mermaid fences — see docs/en/user/mermaid.md for the supported diagram types.
• Label line breaks use <br/>, never \n (literal \n shows as text). All code below is already cleaned.
• Insert faithfully — every diagram must reflect only what the page already describes; invent no product behavior.
• ASCII-art spots are replacements, not additions: protocol "pipeline" + "federation", mcp "How it works", llm-wiki "Two modes" already ship ASCII art — swap the block for the diagram.
• Locate by heading/section, not by the line numbers in the table (those are EN snapshots and drift).

Scope of the first pass

This pass inserts each diagram into the language the analysis sourced it from: EN pages + the RU-only pages (oauth, Импорт из Telegram, Публикация через аккаунты, change_webhooks, cron_webhooks). RU twins of EN pages are not edited yet — they need localized labels and several are flagged for rewrite in the docs audit. See RU parity follow-up.

Not doing

• Datacharts — none recommended. No numeric/time-series data on these pages; the existing *.datachart.csv fixtures already cover the only quantitative datasets.
• Admin screenshots via e2e — fully analyzed (admin-screen → doc-page manifest + a dual-use Playwright toHaveScreenshot() / CAPTURE_DOCS harness), but deferred: too complex for now. The manifest and harness plan are recoverable from the docs-visuals-analysis run if revisited.

Priority table

RU parity follow-up

After this pass, mirror each (+ru) diagram into its RU twin with localized labels (reuse the page's existing Russian terms; keep labels terse; never translate code/property names). Hold these back until handled:

• ru/user/telegram.md — a 70-word stub; rewrite the page before adding the setup/editing flows.
• Pages with no RU twin (publishing, the combined webhooks) — covered by the broader EN↔RU parity work in the docs audit.

Status

• First pass: EN + RU-only pages — done 2026-06-21 (31 blocks across 22 pages; ASCII art replaced in protocol/mcp/llm-wiki)
• RU parity pass: mirror (+ru) diagrams with localized labels
• Render-check each diagram on the built site (catch any Mermaid syntax the platform rejects)

Diagrams (ready-to-paste)

sequenceDiagram
    participant You as Your hub
    participant Ch as Trusted channel
    participant Bob as Bob's hub

    Note over Bob: Admin -> Federation -> Add inbound secret
    Bob->>Bob: Generate secret for kid "alice-2026"<br/>pick allowed subgraphs
    Bob->>Ch: Send kid + secretHex
    Ch->>You: kid + secretHex
    Note over You: Admin -> Federation -> Add outbound secret
    You->>You: Save kid, secretHex, Bob's kb_url
    You->>You: Create KB-note (mcp_federation_kb_url)
    Note over You,Bob: Now your agent can federated_search Bob's base
    Note over You,Bob: Reverse direction (optional): repeat the other way

flowchart TD
    A{KB-note points<br/>at peer?} -->|No, but outbound secret exists| ORPH[orphan_secret]
    A -->|Yes| B{Target is a<br/>pool instance?}
    B -->|No| EXT[external]
    B -->|Yes| C{Outbound secret?}
    C -->|No| NA[no_auth - peer 401s]
    C -->|Revoked| REV[revoked]
    C -->|Yes| D{Peer has matching<br/>inbound secret for kid?}
    D -->|No| OW[one_way - peer 401s]
    D -->|Yes| E{Inbound grants<br/>at least 1 subgraph?}
    E -->|No| NAC[no_access - 0 results]
    E -->|Yes| OK[ok - link works]

stateDiagram-v2
    [*] --> Synced
    Synced --> ServerChanges: server edited a file
    Synced --> LocalChanges: you edited a file
    ServerChanges --> BothChanged: you also edit
    LocalChanges --> BothChanged: server also edits
    BothChanged --> Conflict: same file, both sides
    ServerChanges --> Synced: sync downloads (blue)
    LocalChanges --> Synced: sync uploads (green)
    BothChanged --> Synced: auto-merge (orange)
    Conflict --> Synced: resolve - keep / accept / both (red)

flowchart TD
    A[Obsidian vault] -->|sync plugin| B[trip2g server<br/>your instance]
    B -->|rendering| C[Website<br/>HTML pages, sitemap, RSS]
    C -.optional.-> D[Telegram channel]
    C -.optional.-> E[MCP server]
    C -.optional.-> F[AI assistant]

flowchart LR
    Q[Your query] --> T[Text search<br/>BM25 + morphology]
    Q --> S[Semantic search<br/>OpenAI vector, nearest in meaning]
    T --> R[RRF<br/>Reciprocal Rank Fusion<br/>merge by position]
    S --> R
    R --> F[Final ranking]

flowchart TD
    Open[Reader opens a note] --> Free{free: true?}
    Free -->|Yes| Public[Served to everyone]
    Free -->|No| Login{Signed in?}
    Login -->|No| Paywall[Show preview + paywall / redirect to sign in]
    Login -->|Yes| Sub{Active subscription?}
    Sub -->|Patreon / Boosty / crypto / Telegram group| Grant[Show full note]
    Sub -->|No active access| Paywall

flowchart TD
    N[Note] --> Q{Has subgraph / subgraphs?}
    Q -->|No, untagged| Leak[Visible to EVERY signed-in user]
    Q -->|Yes: assigned subgraph| Gated[Visible only to granted users]
    Leak -. apply frontmatter patch .-> Patched[Reassigned to notes_without_subgraph]
    Patched --> Hidden[Nobody is granted it -> invisible to regular users]
    Hidden --> AdminNote[Admins always see everything]
    Gated --> AdminNote

sequenceDiagram
    participant Admin
    participant trip2g as Trip2G
    participant Reader
    participant Provider as Google / GitHub

    Admin->>trip2g: Add user (email + role)
    Reader->>Provider: Sign in (one click)
    Provider-->>trip2g: Verified email
    alt Email matches a registered user
        trip2g->>Reader: Access granted
    else No matching email
        trip2g->>Reader: Access denied
    end

sequenceDiagram
    participant Author
    participant trip2g
    participant Service as Your service

    Author->>trip2g: Save / delete a note
    Note over trip2g: Note matches a path pattern
    trip2g->>Service: POST payload (changes[], instruction)
    Note right of trip2g: Signed: X-Webhook-Signature sha256
    Service->>Service: Run AI / index / notify
    Service-->>trip2g: { status: ok, changes[] }
    Note over trip2g: Verify expected_hash
    trip2g->>Author: Apply corrected note

flowchart TD
    A[submitForm received] --> B{can_submit allows<br/>this viewer?}
    B -->|admin only, not admin| R1[FormSubmitDeniedPayload<br/>reason admin_required]
    B -->|paid_user| R2[FormSubmitDeniedPayload<br/>reason not_implemented]
    B -->|allowed| C{Valid Turnstile<br/>token?}
    C -->|No| R3[TurnstileRequiredPayload<br/>siteKey]
    C -->|Yes or disabled| D{Fields pass<br/>validation?}
    D -->|No| R4[ErrorPayload<br/>byFields]
    D -->|Yes| R5[SubmitFormPayload<br/>submitId]

sequenceDiagram
    participant Client as AI client
    participant MCP as MCP server (trip2g.com)
    participant KB as Knowledge base (your notes)

    Client->>MCP: Ask a question
    MCP->>KB: Vector search
    KB-->>MCP: Relevant notes
    MCP-->>Client: Note text + author instructions
    Note over Client: Composes answer grounded in your knowledge

flowchart TD
    Q[Question] --> Mode{Base size<br/>& structure}
    Mode -->|Curated / smaller| A1[read index.md]
    A1 --> A2[open relevant pages]
    A2 --> A3[follow wikilinks]
    A3 --> AC[Answer with citations]
    Mode -->|Large / less structured| B1[search query]
    B1 --> B2[inspect matches & TOC]
    B2 --> B3[note_html to load sections]
    B3 --> B4[follow wikilinks]
    B4 --> B5[verify sources]
    B5 --> AC

flowchart TD
    A[Create bot in BotFather] --> B[Add bot token in admin panel TG bots]
    B --> C[Create Telegram channel]
    C --> D[Add bot as channel admin<br/>Post messages + Add members]
    D --> E[Write note in Obsidian]
    E --> F[Add telegram_publish_at + telegram_publish_tags]
    F --> G[Sync the note]
    G --> H{Tag matches?}
    H -->|Instant Tag| I[Publish immediately]
    H -->|Scheduled tag| J[Queued until publish_at]
    I --> K[Post live in channel]
    J --> K

flowchart TD
    E[Want to change a published post] --> Q{What changes?}
    Q -->|Text, formatting,<br/>links, lists| A[Edit note in Obsidian -> Sync<br/>Post updates automatically]
    Q -->|Photos, videos, post type,<br/>number of album photos| B[Open post in admin -> Reset]
    Q -->|Rename the note| B
    B --> C[Edit note in Obsidian]
    C --> D[Sync again<br/>Re-queued and published]

sequenceDiagram
    participant Reader
    participant Frontend
    participant Server

    Note over Frontend: Note rendered with data-line attrs<br/>(allow_task_toggle: true)
    Reader->>Frontend: Click checkbox
    Frontend->>Server: updateNotes patch<br/>find=unchecked, replace=checked
    alt find appears exactly once
        Server-->>Frontend: UpdateNotesSuccessPayload
        Frontend->>Reader: Optimistic UI update
    else duplicate task text
        Server-->>Frontend: UpdateNotesPatchNotFoundPayload
        Frontend->>Reader: cannot toggle - duplicate task
    end

flowchart TD
    Net[Internet] -->|443| Caddy[Caddy<br/>ports 80/443]
    Caddy -->|docs.example.com| T[trip2g :8081]
    Caddy -->|files.example.com| M[MinIO :9000]
    T -->|S3 API| M
    subgraph compose_network_internal
        T
        M
    end

flowchart LR
    A[Get an instance] --> B[Sign in by email]
    B --> C[Configure admin panel]
    C --> D[Install plugin via BRAT]
    D --> E[Create API key]
    E --> F[Connect plugin to site]
    F --> G[Create _index note]
    G --> H[Sync]
    H --> I[Add free: true]
    I --> J[Page is public]

flowchart TD
    P[Пост из канала] --> S{Уже импортирован?}
    S -->|Да| SK[Пропустить]
    S -->|Нет| T[Заголовок из первых 7 слов<br/>без эмодзи и форматирования]
    T --> C{Заголовок уже занят?}
    C -->|Да| ID[Добавить ID сообщения]
    C -->|Нет| K[Создать заметку]
    ID --> K
    K --> M[Метаданные:<br/>channel_id, message_id, publish_at]
    M --> ML[Скачать фото и видео]
    ML --> WL[Ссылки на посты -> wikilinks]

flowchart TD
    Start([Resolve a section]) --> A{Per-note frontmatter?<br/>header: [[my-header]]}
    A -->|set| UseA[Use that note]
    A -->|none| B{Matching glob section?<br/>header_includes: blog/*}
    B -->|matches| UseB[Use highest-priority match]
    B -->|none| C{Auto-load file exists?<br/>_header.md / _footer.md}
    C -->|yes| UseC[Use the auto-load note]
    C -->|no| None[Section absent]

flowchart LR
    Note[Markdown note<br/>layout: my-page] --> Engine{Jet template engine}
    Layout[_layouts/my-page.html<br/>note.Title, note.HTMLString] --> Engine
    Engine --> Page[Complete HTML page]

sequenceDiagram
    participant Agent
    participant API as /_system/renderlayout
    participant Buffer as Ring buffer (10, in-memory)
    participant Human

    Agent->>API: POST { layout.src, note.src }
    API->>Buffer: store rendered HTML (nothing written to vault)
    API-->>Agent: { previewURL, warnings }
    alt warnings non-empty
        Agent->>Agent: read Jet error, fix template
        Agent->>API: POST again
    else all warnings empty
        Agent-->>Human: share previewURL
        Human->>API: GET ?preview_id=xxx
        API-->>Human: rendered HTML
    end

flowchart TD
    A[Cron fires: POST to your endpoint] --> B{Task finishes<br/>under 60s?}
    B -->|Yes| C[Return status: ok + changes]
    C --> D[trip2g applies changes]
    B -->|No| E[Return 202 Accepted]
    E --> F[Agent keeps working]
    F --> G[Write back later via API token]

sequenceDiagram
    participant Visitor
    participant Page
    participant Server

    Visitor->>Page: Fill form, click Submit
    Page->>Server: submitForm (no token)
    Server-->>Page: TurnstileRequiredPayload { siteKey }
    Page->>Visitor: Render Turnstile widget
    Visitor->>Page: Solve captcha
    Page->>Server: submitForm (turnstileToken)
    Server-->>Page: SubmitFormPayload { submitId }
    Page->>Visitor: Redirect to success_url

flowchart TD
    Agent[Your agent] --> Hub[Your trip2g hub]
    Hub -->|no auth| Public[Public base]
    Hub -->|HMAC key| Private[Private peer]
    Hub -->|HMAC key| Adapter[External adapter<br/>GitHub / Telegram]

flowchart TD
    N[Note] --> U{Filename or any<br/>path folder starts with _ ?}
    U -->|Yes| EX[Excluded - system note]
    U -->|No| SF{search: false in frontmatter?<br/>direct or via frontmatter patch glob}
    SF -->|Yes| EX
    SF -->|No| IDX[Indexed - appears in search]

flowchart LR
    A[/_system/mcp] --> D[mcp_method: initialize<br/>default persona]
    B[/_system/mcp?method=wiki] --> W[mcp_method: wiki<br/>free: true -> public]
    C[/_system/mcp?method=premium_advisor] --> P{Subscriber?}
    P -->|Yes| PA[mcp_method: premium_advisor<br/>in-depth advisor]
    P -->|No| E[Method not found 401]
    D --> T[Same tool set]
    W --> T
    PA --> T

flowchart TD
    A[Read note + content hash] --> B[Transform content]
    B --> C[updateNotes with expectedHash]
    C --> D{Hash still<br/>matches?}
    D -->|Yes| E[UpdateNotesSuccessPayload<br/>change applied]
    D -->|No| F[UpdateNotesHashMismatchPayload<br/>actualHash]
    F --> A

flowchart LR
    N[Заметка с тегом Новости] --> R{Каналы с этим тегом}
    R --> C1[Канал A]
    R --> C2[Канал B]
    C1 --> B1[Бот]
    C2 --> B2[Бот]
    C2 --> A2[Аккаунт]
    B1 --> T1[Пост в канале A]
    B2 --> T2[Пост в канале B через бота]
    A2 --> T3[Пост в канале B через аккаунт]

flowchart TD
    Start([Determine page title]) --> T{title frontmatter set?}
    T -->|yes| UseT[Title = frontmatter value<br/>used in title tag, OG, listings]
    T -->|no| H{Leading H1 in body?}
    H -->|yes| UseH[Title = H1 text<br/>no separate title element rendered]
    H -->|no| File[Title = filename]
    UseT --> H1check{Leading H1 also present?}
    H1check -->|yes| Skip[Template skips its own title element<br/>shows only the in-content H1]
    H1check -->|no| Render[Template renders its title element]