diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bc69969
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# dsh-vk-group
+
+DeepSeek Harness plugin (bundle) that gives the agent a complete VKontakte community-management toolkit: 30 model tools, a LongPoll event bridge, and a rule-based moderation engine.
+
+> Status: **design / plan stage.** The architecture, tool surface and wiki are complete. No implementation code yet.
+
+## What it does
+
+- **30 model tools** covering community info & settings, members, bans, join requests, managers, wall posts, comments, media upload, board topics, market products, community messages, stats, shortlinks, Callback API servers and LongPoll control.
+- **LongPoll bridge** — incoming messages, comments, joins, board replies and market comments are delivered to the agent as durable context via `agent.followup()`.
+- **Moderation engine** — keyword/regex/new-member/link rules evaluated without the model in the loop, with a warn threshold and an append-only audit log.
+- **Safety layer** — destructive operations route through `tools/pre-execute` with an `ask` decision, a monotonic `ctx.tools.guard()` blocks writes when the token lacks admin rights, `dryRun` is on by default for settings changes, and the raw-API escape hatch is disabled unless explicitly enabled.
+
+## Requirements
+
+| | |
+|---|---|
+| DeepSeek Harness | `>=0.2.0 <0.3.0` |
+| Node.js | `>=20` |
+| VK token | community token (required) + user token (recommended, unlocks `stats.get`, `groups.getMembers`, `groups.getBanned`) |
+
+### VK token scopes
+
+Community token: `manage`, `wall`, `photos`, `docs`, `messages`, `market`, `stories`, `topics`.
+
+User token adds: `groups`, `stats`, `offline`.
+
+Without a user token these tools return a typed `VK_SCOPE_MISSING` error instead of failing obscurely: `vk_members_list`, `vk_stats_get`, parts of `vk_ban_list`.
+
+## Install
+
+```sh
+# from a tarball (recommended — ships prebuilt dist/)
+dsh plugin --profile web add ./dsh-vk-group-0.1.0.tgz
+
+# from git (requires allowlisting the prepare script, see the wiki)
+dsh plugin --profile web add github:hermes/dsh-vk-group
+```
+
+Then add the configuration to your profile's `cordis.patch.yml`:
+
+```yaml
+- id: vk-group
+  name: dsh-vk-group
+  config:
+    groupId: -123456789
+    accessToken: !!js process.env.VK_COMMUNITY_TOKEN
+    userAccessToken: !!js process.env.VK_USER_TOKEN
+    longpoll:
+      enabled: true
+```
+
+Restart `dsh web`, then verify with `dsh --profile web --dump-config` — the layer should show `# == dsh-vk-group`.
+
+## Tool surface
+
+See the repository wiki, page **Tools Reference**. Summary:
+
+| Group | Tools |
+|---|---|
+| Community | `vk_community_info`, `vk_community_update` |
+| Members | `vk_members_list`, `vk_members_manage`, `vk_member_status` |
+| Moderation | `vk_ban_list`, `vk_ban_manage`, `vk_requests_list`, `vk_requests_handle` |
+| Managers | `vk_managers_list`, `vk_manager_set` |
+| Wall | `vk_wall_post`, `vk_wall_edit`, `vk_wall_delete`, `vk_wall_pin`, `vk_wall_list` |
+| Comments | `vk_comments_list`, `vk_comment_manage` |
+| Media | `vk_media_upload` |
+| Board | `vk_board_topic`, `vk_board_comment` |
+| Market | `vk_market_manage` |
+| Messages | `vk_messages_send`, `vk_messages_list` |
+| Analytics | `vk_stats_get`, `vk_shortlink` |
+| Infrastructure | `vk_callback_manage`, `vk_longpoll_control`, `vk_moderation_rules`, `vk_api_raw` |
+
+## Development
+
+```sh
+npm install
+npm run build      # tsdown → dist/
+npm test           # vitest
+```
+
+## License
+
+MIT