Инструкция для внешнего агента: первый бесплатный инстанс Trip2G

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

Пользователь не должен начинать знакомство с Trip2G с технической настройки. Внешний агент должен провести его как рассказчик и редактор:

одна реальная идея / папка / источник
  → короткое интервью
  → первая structured knowledge page
  → инструкция для агентов рядом с базой
  → index/log
  → проверочный вопрос через MCP или index-first traversal

Для работы агенту обычно нужны:

1. URL бесплатного инстанса Trip2G.
2. Архив vault, который выдаёт сам Trip2G/simplecloud, — это не просто папка с заметками. Внутри уже может быть настроенный Obsidian plugin с API key для sync.
3. Отдельный Trip2G sync/API token нужен только если архива с настроенным plugin/key нет, ключ невалиден, или агенту выдают scoped/temporary token вместо полного архива.
4. Admin cookie/token только если агент должен открыть admin UI или менять admin-настройки: frontmatter patches, templates, domains, access rules или webhooks.

Не надо по умолчанию просить admin cookie. Сначала нужно понять задачу и использовать минимальный доступ.

Важно: теоретически агент может получить admin session и другим путём — выполнить login/auth mutation, запросить одноразовый код с почты у пользователя и завершить авторизацию. Но это сложнее, медленнее и требует координации с пользователем. Если пользователь уже нажал фиолетовую кнопку simplecloud и открыл instance как админ, проще и надёжнее передать агенту текущую admin cookie как временный secret, если admin-доступ действительно нужен.

Где пользователь получает бесплатный инстанс

Пользователь может получить один бесплатный Trip2G instance здесь:

https://simplecloud.2pub.me/

Сценарий для пользователя:

1. Открой https://simplecloud.2pub.me/
2. Зарегистрируйся или войди через GitHub/Google.
3. Создай/получи бесплатный instance.
4. После создания появится фиолетовая кнопка «открыть как админ» / открыть admin site.
5. Открой instance как админ.
6. В админке скачай архив vault/site, если интерфейс предлагает скачать архив.
7. Передай агенту:
   - URL instance;
   - скачанный архив;
   - admin cookie только если агент должен сам войти в админку и менять настройки.

Пояснение для пользователя:

Архив нужен агенту, чтобы получить текущую структуру Trip2G vault и уже настроенный Obsidian sync plugin/API key. Это основной способ дать агенту возможность готовить и синхронизировать изменения без отдельной ручной настройки CLI.
Admin cookie нужен не всегда. Он нужен, если агент должен сам открыть админку, скачать архив, настроить доступы/templates/frontmatter patches/webhooks или синхронизировать через admin-only API.

Если cookie не передавать, агент может попробовать пройти login flow через auth mutation и одноразовый код с почты: агент запускает запрос кода, пользователь присылает код, агент завершает login и получает session. Но для первого onboarding это хуже: больше шагов, выше риск сломаться, пользователь уже фактически авторизован фиолетовой кнопкой. Поэтому для admin-only задач проще использовать cookie из текущей Chrome-сессии как временный secret.

Важно: архив считается чувствительным, потому что внутри может лежать `.obsidian/plugins/trip2g/data.json` с API key. Не публикуй архив в открытых местах.

http://trip2g.com/_system/mcp

- чтобы не угадывать, как работают Trip2G templates/frontmatter/webhooks/MCP/federation;
- чтобы агент мог искать по документации движка;
- чтобы агент мог отличать “что поддерживает Trip2G” от собственных предположений;
- чтобы при настройке бесплатного инстанса агент мог читать актуальные инструкции из Trip2G docs.

1. Добавь `http://trip2g.com/_system/mcp` как MCP server / knowledge base в агентном клиенте, если клиент поддерживает MCP.
2. Перед изменениями в инстансе сначала спроси эту базу:
   - как настроить frontmatter patches;
   - как работает default template;
   - как устроен sync/API;
   - как создавать `_header.md`, `_footer.md`, `_index.md`;
   - как устроены webhooks/cron;
   - как работает federation.
3. В отчёте явно разделяй:
   - “нашёл в docs движка”;
   - “проверил на пользовательском instance”;
   - “предположил, но не проверил”.

CLI для синхронизации

Если агент будет работать локально с архивом и потом загружать изменения в Trip2G, ему пригодится официальный sync CLI:

https://github.com/trip2g/obsidian-sync/releases/download/0.3.5/trip2g-sync.mjs

Команда скачивания:

mkdir -p ./bin
curl -fsSL \
  https://github.com/trip2g/obsidian-sync/releases/download/0.3.5/trip2g-sync.mjs \
  -o ./bin/trip2g-sync.mjs
node ./bin/trip2g-sync.mjs --help

Синхронизация обычно выглядит так:

node ./bin/trip2g-sync.mjs ./vault \
  --api-url https://YOUR_INSTANCE.2pub.me/graphql \
  --api-key "$TRIP2G_API_KEY" \
  --two-way \
  --conflict-resolution local \
  --verbose

Не вставлять API key прямо в команду в чате. Лучше передавать через env/secret.

Как достать admin cookie в Chrome, если всё-таки нужно

Использовать только если агенту реально нужен admin-доступ.

Инструкция для пользователя:

1. Открой свой Trip2G instance как админ через фиолетовую кнопку на simplecloud.
2. Убедись, что в адресной строке открыт именно твой instance, например:
   https://your-name.2pub.me/admin
3. Нажми F12 или Cmd+Option+I / Ctrl+Shift+I, чтобы открыть DevTools.
4. Перейди во вкладку Application.
5. Слева открой Storage → Cookies.
6. Выбери домен своего instance: https://your-name.2pub.me
7. Найди cookie с названием вроде `trip2g_token` или похожим auth/session token.
8. Скопируй Name и Value.
9. Передай агенту в формате:
   trip2g_token=VALUE

Альтернативный способ через Network:

1. Открой DevTools → Network.
2. Обнови страницу admin.
3. Кликни любой запрос к твоему домену.
4. В Headers найди Request Headers → Cookie.
5. Скопируй только auth-cookie для Trip2G, не весь набор лишних cookies, если возможно.

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

- Не публикуй cookie в общем чате, GitHub issue, markdown-файле или скриншоте.
- Передавай cookie только как secret/env, если интерфейс агента это умеет.
- После работы выйди из аккаунта или перевыпусти/отзови сессию, если есть такая возможность.
- Если сомневаешься, сначала дай агенту архив без cookie: часто этого достаточно.

Кому адресована инструкция

Эта инструкция для агента другого человека, который получил бесплатный Trip2G instance и хочет быстро понять ценность продукта.

Агент должен:

• не утопить пользователя в MCP/API/frontmatter jargon;
• создать первый полезный artifact;
• объяснить новый способ работы: база содержит не только знания, но и правила для агентов;
• безопасно принять archive/token/cookie, если они нужны;
• оставить после себя понятную структуру, которую другой агент сможет продолжить.

Что спросить у пользователя в начале

Скажи пользователю:

Давай сделаем первую Trip2G-базу за один небольшой проход.

Мне нужно понять, что ты хочешь превратить в knowledge base:

1. Одна идея, которую надо оформить?
2. Папка заметок / Obsidian vault?
3. Документация проекта?
4. Research по теме?
5. База для Claude/Cursor/Codex, чтобы агенты могли искать и продолжать работу?

Потом спроси:

Какой первый результат ты хочешь увидеть?

A. Публичная страница идеи.
B. Приватная база для агентов.
C. MCP-search по заметкам.
D. LLM Wiki: index.md + log.md + AGENTS.md + несколько concept pages.
E. Landing/demo page.

Какие данные попросить

1. URL твоего Trip2G instance.
2. 1–3 абзаца идеи или один markdown-файл.
3. Нужно публично, приватно или доступ по ссылке?

.obsidian/plugins/trip2g/data.json

1. Пользователь скачивает архив из admin UI.
2. Передаёт архив агенту как чувствительный файл.
3. Агент распаковывает архив локально.
4. Агент читает `.obsidian/plugins/trip2g/data.json` программно, не печатая ключ.
5. Агент скачивает/использует `trip2g-sync.mjs`.
6. Агент синхронизирует изменения через API key из plugin config.

1. Архив `.zip` с vault/папкой markdown.
2. Какие папки импортировать, а какие игнорировать.
3. Можно ли публиковать часть файлов.
4. Что должно стать главной страницей.
5. Какие агенты будут читать базу: Claude, Cursor, Codex, Hermes, другое.

Перед отправкой архива удали или явно отметь секретные файлы: `.env`, cookies, API keys, private credentials, client data.
Если не уверен — отправь сначала список файлов без содержимого.

- архива из Trip2G нет;
- в архиве нет `.obsidian/plugins/trip2g/data.json`;
- ключ из архива не работает;
- пользователь хочет дать scoped/temporary token вместо полного архива;
- агент должен писать только в ограниченную папку.

Если хочешь, чтобы я сам загрузил изменения в твой Trip2G instance, пришли временный Trip2G API/sync token или настрой scoped token с правами только на нужную папку.

Не вставляй token в публичный чат. Передай его как secret/env, если твой агентный интерфейс это поддерживает.

Admin cookie нужен только если я должен менять настройки инстанса.
Если задача — загрузить markdown и создать первую базу, лучше дать sync/API token вместо admin cookie.

Если admin cookie всё-таки нужен:
- передай его как secret/env, не в markdown и не в финальный отчёт;
- желательно временно и с возможностью отозвать;
- после работы отзови/перевыпусти cookie/token.

Правило минимального доступа

Используй такую матрицу:

Нужно только написать пример страницы → token/cookie не нужны.
Нужно загрузить markdown → sync/API token.
Нужно читать приватные страницы → read-scoped token или cookie.
Нужно менять настройки публикации/access/templates → admin cookie/token.
Нужно отладить UI/admin → admin cookie + browser session.

Как хранить секреты во время работы

Агент должен соблюдать правила:

- Никогда не записывать cookie/API key в markdown-заметки.
- Никогда не печатать cookie/API key в финальный ответ.
- Никогда не вставлять token в commit/log/report.
- Редактировать tool output, если там случайно появился token.
- После завершения рекомендовать пользователю отозвать временный secret.

Если агент запускается в shell/docker:

export TRIP2G_INSTANCE="https://example.2pub.me"
export TRIP2G_API_KEY="..."
export TRIP2G_ADMIN_COOKIE="trip2g_token=..." # только если реально нужно

В отчётах писать только:

TRIP2G_API_KEY=[REDACTED]
TRIP2G_ADMIN_COOKIE=[REDACTED]

Storyteller onboarding: что говорить пользователю

Начни не с файлов, а с истории:

Trip2G — это не просто место, где лежат markdown-файлы.
Это база знаний, которая сама объясняет агентам, как её читать.

Давай создадим первую маленькую базу:
- одна главная страница;
- index.md, чтобы агент понимал карту;
- log.md, чтобы следующий агент видел историю;
- AGENTS.md, чтобы база давала инструкции;
- 1–3 страницы знаний по твоей идее или источникам.

Потом спроси:

Дай мне одну идею, ссылку, документ или архив.
Я превращу это в первую Trip2G-базу, которую можно читать как сайт и использовать как память для агентов.

Первый deliverable агента

После получения идеи/архива агент должен создать:

_index.md           # главная страница для Trip2G
AGENTS.md           # инструкция для агентов
SCHEMA.md           # правила страниц
index.md            # карта базы для index-first traversal
log.md              # журнал изменений
concepts/...        # первые concept pages
sources/... или raw/... # исходники, если уместно

Для очень маленького первого теста достаточно:

_index.md
AGENTS.md
index.md
log.md

Советы из LLM Wiki подхода

Используй Trip2G не как “папку markdown”, а как LLM Wiki: устойчивый артефакт знания, который переживает чат.

Главное правило:

The wiki is the artifact, not the chat.

По-русски:

Артефакт — это база/wiki, а не переписка с агентом.

Мы не просто загрузим заметки.
Мы сделаем маленькую базу, которую следующий агент сможет читать и продолжать:

- index.md покажет карту базы;
- log.md покажет, что уже происходило;
- AGENTS.md объяснит агентам, как пользоваться базой;
- concept pages сохранят устойчивые идеи;
- raw/source files останутся источником правды.

Source / idea / question
  ↓
agent reads index.md + existing pages
  ↓
agent creates or updates structured pages
  ↓
agent links pages with wikilinks
  ↓
agent updates index.md
  ↓
agent appends log.md
  ↓
next agent starts from wiki, not from zero

Question → read index.md → open relevant pages → follow wikilinks → answer with citations

Question → search/RAG → open strongest pages → follow wikilinks → verify raw sources if needed → answer

- каждая важная страница имеет sources;
- raw/source файлы не редактируются;
- спорные утверждения помечаются как contested/uncertain;
- human-written секции не перезаписываются молча;
- хорошие ответы сохраняются обратно только если они будут полезны позже;
- дубли страниц не создаются без проверки index.md;
- каждая операция попадает в log.md.

Прочитай index.md этой Trip2G-базы, открой релевантные страницы и объясни, что здесь уже известно. Не используй поиск, если index.md достаточно.

Найди одну полезную новую связь между страницами, предложи обновление index.md и запиши это в log.md.

MCP properties для AGENTS.md, SCHEMA.md и дополнительных инструкций

В документации Trip2G найдено два важных правила:

1. В user-facing MCP docs есть метод instructions() и пример заметки с frontmatter:

---
mcp_method: instructions
---

2. В dev docs описаны динамические MCP tools: любая публичная заметка с mcp_method в frontmatter может стать callable tool; mcp_description попадает в tools/list как описание.

Поэтому первая база должна не только иметь AGENTS.md и SCHEMA.md, но и выставлять их как MCP-доступные инструкции.

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

AGENTS.md  → mcp_method: instructions  # канонический метод инструкций из user docs
SCHEMA.md  → mcp_method: schema        # схема базы, типы страниц, frontmatter
_mcp_initialize.md или AGENTS.md → mcp_method: initialize  # короткий startup protocol, если нужен отдельный init tool

Важно: свойство называется mcp_description, не mcp_descrption.

---
free: true
mcp_method: instructions
mcp_description: "How agents should read, update, cite and maintain this Trip2G knowledge base."
---
# Agent Instructions

---
free: true
mcp_method: initialize
mcp_description: "Start here: initialize a session with this Trip2G knowledge base."
---
# Initialize this knowledge base

1. Read `index.md`.
2. Read latest entries in `log.md`.
3. Read `AGENTS.md` via `instructions()`.
4. Read `SCHEMA.md` via `schema()` if you will create or edit pages.
5. Decide retrieval mode:
   - small base: index-first traversal;
   - large/uncertain base: search/RAG + linked-page verification.
6. Report what you read before making changes.

---
free: true
mcp_method: schema
mcp_description: "Schema for this Trip2G LLM Wiki: page types, required frontmatter, folders and update rules."
---
# Knowledge Base Schema

## Page types

- `concept` — durable concept page.
- `source` — raw or source-derived page.
- `query` — useful answer saved for reuse.
- `comparison` — reusable comparison.
- `decision` — decision and rationale.
- `log` — append-only chronological history.

## Required frontmatter

```yaml
type: concept | source | query | comparison | decision | log
status: draft | verified | contested
sources:
  - url-or-wikilink
updated: YYYY-MM-DD

Update rules

1. Do not edit raw sources.
2. Preserve provenance.
3. Mark uncertain claims as contested.
4. Update index.md when adding durable pages.
5. Append every meaningful change to log.md.

### Дополнительные instruction tools

Для крупных баз можно добавить отдельные MCP methods:

```markdown
---
free: true
mcp_method: retrieval_policy
mcp_description: "When to use index-first traversal, search/RAG, similar notes and raw source verification."
---

---
free: true
mcp_method: source_policy
mcp_description: "How to handle sources, provenance, uncertainty and contested claims."
---

---
free: true
mcp_method: editor_role
mcp_description: "Tone, answer style and editorial rules for this knowledge base."
---

Не делай слишком много methods на старте. Для первого инстанса достаточно:

instructions()
schema()
initialize() — optional

Минимальный AGENTS.md для первой базы

---
free: true
mcp_method: instructions
mcp_description: "How agents should read, update, cite and maintain this Trip2G knowledge base."
---
# Agent Instructions

You are working with a Trip2G knowledge base.

This base is not just a folder of notes. It contains instructions for how agents should read, update and cite knowledge.

## Start every session

1. Read `index.md`.
2. Read the latest entries in `log.md`.
3. Use search/RAG only if `index.md` is insufficient.
4. Open relevant pages and follow wikilinks one hop.
5. Answer with citations to pages you actually read.

## Retrieval policy

Use index-first traversal by default:

Question → `index.md` → relevant pages → wikilinks → answer.

Use Trip2G search/RAG when:

- the base is large;
- exact terms matter;
- index does not reveal relevant pages;
- the user asks for source verification.

## Updating the base

If a result is useful beyond the current chat:

1. Save it as a page.
2. Add it to `index.md`.
3. Append an entry to `log.md`.
4. Preserve source links and uncertainty.

## Do not

- invent citations;
- overwrite human-written sections silently;
- create duplicate pages before checking `index.md`;
- put secrets into markdown;
- treat summaries as truth without sources.

Минимальный index.md

# Knowledge Base Index

> Read this first. This is the map of the base.

## How to use

1. Start here.
2. Open 2–5 relevant pages.
3. Follow wikilinks.
4. Use search only if this map is insufficient.

## Main pages

- [[_index]] — public/home page.
- [[AGENTS]] — instructions for agents.
- [[log]] — chronological history.

## Concepts

- [[concepts/main-idea]] — the first idea/source in this base.

Минимальный log.md

# Knowledge Base Log

## YYYY-MM-DD — base initialized

- Created first Trip2G knowledge base.
- Added `_index.md`, `AGENTS.md`, `index.md`, `log.md`.
- Next: connect MCP client or add first source.

Что делать с архивом пользователя

Если пользователь скинул архив:

1. Распакуй в отдельную рабочую папку.
2. Сначала составь inventory, не публикуй сразу.
3. Найди потенциальные секреты:
   • .env
   • credentials
   • cookie
   • token
   • api_key
   • private client names/data
4. Спроси или сам исключи явные секреты.
5. Выбери 5–20 файлов для первого MVP, не пытайся импортировать всё.
6. Создай index.md как карту.
7. Создай AGENTS.md под конкретную базу.
8. Добавь log.md.
9. Только после этого sync/upload.

Что делать с admin cookie

Ответ на вопрос “ему нужно будет скинуть архив как админ и куку?”:

Архив — да, если нужно перенести существующие заметки/доки.
Admin cookie — не обязательно и не первым делом.

Правильнее:

1. Сначала дать агенту URL instance и архив/пример контента.
2. Если агент должен только подготовить файлы — cookie не нужен.
3. Если агент должен загрузить файлы — дать sync/API token.
4. Если агент должен менять настройки admin — только тогда дать admin cookie/token.

Безопасная формулировка для пользователя

Агент может отправить пользователю такой текст:

Пришли мне, пожалуйста:

1. URL твоего Trip2G instance.
2. Архив markdown/Obsidian vault, если хочешь импортировать существующие заметки.
3. Что должно получиться первым: публичная страница, приватная база для агента, docs-to-MCP или LLM Wiki.
4. Если хочешь, чтобы я сам загрузил результат — временный Trip2G sync/API token.

Admin cookie нужен только если я должен менять настройки в админке: доступы, templates, frontmatter patches, webhooks или домены. Если можно обойтись API/sync token — лучше не присылай admin cookie.

Не присылай секреты в публичный чат. Если в архиве есть `.env`, cookies, API keys или приватные данные — удали их или предупреди меня.

Проверка результата

После работы агент должен вернуть пользователю:

Создано:
- файл/страница
- файл/страница

Как читать:
- начни с index.md
- агентам читать AGENTS.md

Как проверить:
- задай агенту вопрос: ...
- ожидаемый путь: index.md → page → answer with citations

Что дальше:
- подключить MCP
- добавить sources
- настроить public/private
- включить cron/webhook

Acceptance criteria

Работа хорошая, если:

• пользователь получил первый visible artifact, а не только настройку;
• есть AGENTS.md рядом с базой;
• есть index.md для index-first traversal;
• есть log.md для следующего агента;
• secrets не попали в markdown;
• admin cookie не запрашивался без необходимости;
• пользователь понимает, что Trip2G — это база знаний, которая инструктирует агентов, а не просто сайт с заметками.

Связанные заметки

• Исследование trip2g/15 - Первый рассказчик onboarding для Trip2G
• Исследование trip2g/16 - Лендинг Trip2G под LLM Wiki
• Исследование trip2g/17 - Инструкция для Trip2G LLM Wiki базы