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.
Set up the project structure per the new-project guide, adapted from the
Python skeleton to the Node/TS stack fixed in SPEC.md (reuses docmost-mcp).
Scaffold only — the sync engine is not implemented yet.
- src/settings.ts: single config layer on zod, schema keyed by real ENV
names; credentials and own-service address have no default (fail fast).
- src/config-errors.ts: loadSettingsOrExit — clear startup message naming
the missing/invalid env var instead of a raw stack trace; exit(1).
- src/index.ts: thin entry point that validates config and logs (stub).
- test/: vitest unit tests for settings parsing and config errors (10 tests).
- Makefile (install/env/build/test/run/dev/clean), strict tsconfig, vitest.
- Dockerfile (single-stage, no EXPOSE, prunes dev deps), docker-compose
(daemon, volume on /app/data, watchtower), ghcr CI with build needs test.
- .env.example, .gitignore/.dockerignore, AGENTS.md, README.md.
- Pinned deps (dotenv, zod) + committed package-lock.json.
Research Docmost source (docmost/docmost@main) to close the last four §12 items.
- auth: dedicated service user; API-key (EE/Cloud) vs login JWT (OSS, 90d default,
no refresh, session-bound) with "401 -> re-login"
- position: reuse `fractional-indexing-jittered` generateJitteredKeyBetween,
siblings via /sidebar-pages, compare as raw bytes (COLLATE "C")
- initial clone: canonical = sidebar-pages walk + /info via our converter;
spaces/export (turndown markdown, no meta/anchors) is bootstrap-only, not baseline
- attachments: v1 keeps them as links (out of scope), includeAttachments flag noted
- §16: add auth/JWT/API-key facts, /sidebar-pages, bulk export endpoints,
extra gotchas (collation, throttling, EE-only API keys)
- park "REST vs direct Postgres" as the sole remaining open question
Research Docmost source (docmost/docmost@main) to pin real REST endpoints
and close all five §12 TODOs.
- §6: replace MCP `list_pages` polling with the real "changes since T"
mechanism — `POST /api/pages/recent` (updatedAt DESC, cursor) + client cutoff
- §8: concrete trash/restore endpoints (per-space `trash`, `restore`),
auto-purge note and `permanentlyDelete` guard
- §10: add `lastUpdatedById` loop-guard signal
- §12: turn open questions into decisions (trash/restore, changes-since-T,
commit-attribution trailer, filename collisions, long-offline reconciliation);
add a new list of genuinely-open items
- §15/§16: add the confirmed Docmost REST map (auth, info, recent, create,
update, move, move-to-space, delete, trash, restore) with gotchas
- fix a nested-list markdown glitch in §12
