From 2f92dc4c1f05bebd5f4431aef71bf8982e617921 Mon Sep 17 00:00:00 2001
From: vvzvlad <git@vvzvlad.xyz>
Date: Tue, 16 Jun 2026 19:11:53 +0300
Subject: [PATCH] docs(spec): add monorepo implementation and access layer
 notes

Add documentation of the monorepo layout, describing the `docmost-client` and `sync` packages and their responsibilities. Clarify that all Docmost access is performed via REST for reads, while writes use collab/Yjs, documenting the architectural decision and its rationale.
---
 SPEC.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/SPEC.md b/SPEC.md
index f441005..1f54bc7 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -27,6 +27,11 @@
 - lossless-конвертер `convertProseMirrorToMarkdown` / `markdownToProseMirror`;
 - collab-путь записи `replacePageContent` / `mutatePageContent` (Hocuspocus/Yjs).
 
+Реализация — **monorepo (npm workspaces)**: `packages/docmost-client` (выносной
+`DocmostClient` + `lib/*`, лейаут 1:1 с `docmost-mcp/src/` — sync-методы дописываем
+сюда, изменения бэкпортятся в `docmost-mcp` вручную) и `packages/sync` (движок
+синхронизации).
+
 **Важно:** MCP-инструменты — это тонкая обёртка над HTTP API Docmost. Синк-движок
 ходит в REST Docmost **напрямую** и волен использовать любые эндпойнты, которых
 нет в MCP (в частности — листинг корзины и restore, см. §8).
@@ -323,7 +328,11 @@ git диффает побайтово. Если export недетерминир
   Будущая фаза (флаг `includeAttachments` у export уже есть) сможет качать бинари
   в vault и переписывать ссылки. Сейчас — вне scope.
 
-### Остаются открытыми
+### Решение по слою доступа
+- **Доступ к Docmost — всегда REST** (решено). Прямое чтение Postgres отвергнуто:
+  выигрыш на чтении не окупает связку с внутренней схемой, обход сайд-эффектов
+  сервисов (поиск/аудит/websocket) и недоступность против Docmost Cloud. Запись —
+  через collab/Yjs (§2), чтение — REST (§16).
 
 ---