docs: add a README at the repository root

Also list fcgiwrap, which serves cgit on git.meshbay.org, among the
legitimate services of meshbay.org in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2 files changed, 68 insertions, 1 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index c6a27af..4d8a208 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -953,7 +953,7 @@ here are kept only where they are a rule about *editing* the code.
 - SSH: `ssh cbesson@meshbay.org`
 - Caddy: HTTPS reverse proxy on 80/443
 - UFW rules: **22/tcp, 80/tcp, 443/tcp only**
-- Legitimate services: `meshbay-hub.service`, Caddy, PostgreSQL (local)
+- Legitimate services: `meshbay-hub.service`, Caddy, PostgreSQL (local), `fcgiwrap` (cgit on git.meshbay.org)
 - Detailed inventory: `QE/server-state/meshbay.org.md`
 - Hub deployment: see `QE/server-state/meshbay.org.md`
 
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..45ff17c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,67 @@
+# MeshBay
+
+MeshBay is a platform for **private, encrypted, self-hosted groups with an
+application store**. A group is a set of people, a set of directories on
+somebody's machine, and a set of applications over them — chat, files, video,
+music, photos. Files stay on the machine that shares them and travel encrypted,
+peer to peer; the hub only introduces machines to each other and never sees a
+file, a message or a key.
+
+It is not a public file-sharing network. Public groups are an optional hub
+feature, and they are off on the reference deployment, [meshbay.org](https://meshbay.org).
+
+```
+   your machine                        hub                          a member
+   ────────────                        ───                          ────────
+   meshbay-node  ◄─── signalling ────►  accounts,   ◄─── sign-in ───►  browser
+   holds the files                      group list,                   or desktop
+   holds the group key                  introductions                 client
+        │                                                                │
+        └──────────── encrypted, peer to peer, direct ───────────────────┘
+```
+
+## Getting started
+
+- **Using MeshBay:** [`docs/QUICKSTART.md`](docs/QUICKSTART.md) turns one Linux
+  machine into a node and invites a second person;
+  [`docs/USERGUIDE.md`](docs/USERGUIDE.md) explains every step.
+- **Running your own hub:** [`docs/PACKAGING-GUIDE.md`](docs/PACKAGING-GUIDE.md),
+  [`docs/HTTPS.md`](docs/HTTPS.md) and [`docs/MAIL-SERVER.md`](docs/MAIL-SERVER.md).
+- **How it works:** [`docs/MESHBAY_DESIGN.md`](docs/MESHBAY_DESIGN.md) is the
+  architecture specification, and
+  [`docs/MESHBAY_NODE_PROTOCOL.md`](docs/MESHBAY_NODE_PROTOCOL.md) the wire format.
+
+## Repository layout
+
+| Path | Contents |
+|---|---|
+| `packages/meshbay-common/` | Shared cryptography and protocol types |
+| `packages/meshbay-hub/` | Hub server (FastAPI + PostgreSQL) and the web client it serves |
+| `packages/meshbay-node/` | Node daemon, its CLI and its local control UI |
+| `packaging/` | `.deb`, `.rpm` and Windows packaging, systemd units, Caddy and firewall configuration |
+| `docs/` | Design specification, protocol, user and operator guides |
+| `man/` | Manual page for `meshbay-node` |
+| `site/` | Static website pages (not deployed) |
+| `poc/` | Early proof-of-concept scripts, kept for reference |
+
+## Development
+
+Python 3.12 or later. All dependencies are declared in the packages'
+`pyproject.toml` files:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e "packages/meshbay-common[dev]" -e "packages/meshbay-hub[dev]" \
+            -e "packages/meshbay-node[dev]"
+.venv/bin/pytest
+```
+
+## Source
+
+A read-only public mirror is browsable at <https://git.meshbay.org/> and can be
+cloned with:
+
+```bash
+git clone https://git.meshbay.org/meshbay.git
+```