diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c6071ff
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.DS_Store
+.env
+.env.*
+plugin/main.js
+plugin/node_modules/
+plugin/coverage/
+supabase/.temp/
diff --git a/README.md b/README.md
index 8cbc063..eb69971 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,40 @@
-# obsidian-telegram
-Connector between obsidian and telegram via Supabase.
+# Obsidian Telegram
+
+Telegram-to-Obsidian sync plugin with a Supabase backend.
+
+This repository is a monorepo for:
+- the Obsidian plugin in `plugin/`
+- Supabase schema and Edge Functions in `supabase/`
+- setup and verification scripts in `scripts/`
+- planning docs in `docs/`
+
+## Repository Layout
+
+```text
+obsidian-telegram/
+├── plugin/
+├── supabase/
+├── scripts/
+└── docs/
+```
+
+## Current Status
+
+The repository is scaffolded for the revised architecture:
+- server-side Telegram webhook storage
+- per-client cursor sync, not global message sync flags
+- topic-aware routing
+- self-hosted Supabase bootstrap from one repo
+
+## Quick Start
+
+1. Run `npm run verify`.
+2. Configure Supabase CLI and project credentials.
+3. Run `npm run bootstrap:supabase`.
+4. Install plugin dependencies with `npm install --prefix plugin`.
+5. Build the plugin with `npm run build:plugin`.
+
+## Notes
+
+- The plugin scaffold follows the official Obsidian sample plugin structure, adapted to live in `plugin/`.
+- The implementation plan for this repo is in [docs/plans/2026-03-03-telegram-sync-server-revised.md](docs/plans/2026-03-03-telegram-sync-server-revised.md).
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..e0d0bba
--- /dev/null
+++ b/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "obsidian-telegram",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Monorepo for the Obsidian Telegram plugin and Supabase backend",
+  "scripts": {
+    "verify": "node scripts/verify-local-env.mjs",
+    "bootstrap:supabase": "node scripts/bootstrap-supabase.mjs",
+    "build:plugin": "npm run build --prefix plugin",
+    "dev:plugin": "npm run dev --prefix plugin",
+    "test:plugin": "npm run test --prefix plugin"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}