1 files changed, 94 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3f05a06
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,94 @@
+# MeshBay — Project Conventions
+
+## What this project is
+
+MeshBay is a decentralized peer-to-peer platform for file sharing, video streaming, and group messaging.
+See `docs/meshbay-draft-v3.md` for the architecture specification.
+
+## Repository structure
+
+```
+meshbay/
+├── packages/
+│   ├── meshbay-common/   # Shared crypto + protocol — python3-meshbay-common RPM
+│   ├── meshbay-hub/      # Hub server (FastAPI + PostgreSQL) — meshbay-hub RPM
+│   └── meshbay-node/     # Node daemon + local UI — meshbay-node RPM
+├── poc/                  # POC spike scripts (reference, not production)
+└── docs/                 # Architecture drafts and POC plans
+```
+
+## Python environment
+
+- **Minimum Python:** 3.12
+- **Package manager:** uv (`uv sync` at root installs all workspace packages in editable mode)
+- **Build backend:** hatchling (per package `pyproject.toml`)
+
+```bash
+# Install dev environment
+uv sync
+
+# Run hub (dev mode)
+uv run meshbay-hub
+
+# Run node (dev mode)
+uv run meshbay-node
+
+# Run tests
+uv run pytest
+```
+
+## Code conventions
+
+- **Linter/formatter:** ruff (`uv run ruff check .` / `uv run ruff format .`)
+- **Line length:** 100
+- **Type hints:** required on all public functions
+- **Comments:** only when the WHY is non-obvious; no docstrings restating the function name
+- **No prints in library code** — use `logging` module
+
+## Versioning
+
+### Package versions (SemVer)
+- Format: `MAJOR.MINOR.PATCH`
+- Pre-1.0: breaking changes bump MINOR, not MAJOR
+- All three packages share the same version number (released together)
+
+### Protocol versions (independent)
+- MNP: `0.1` → bumped independently of package version
+- MHP: `0.1` → bumped independently of package version
+- Every wire message carries a `v` field
+- Breaking change → MAJOR bump; backward-compatible → MINOR bump
+- N-2 MINOR backward compatibility guaranteed
+
+## Commit messages (Conventional Commits)
+
+```
+feat(node): add directory watcher with watchdog
+fix(hub): include jti in all JWT tokens
+chore(common): add Argon2id calibration to crypto.py
+docs: update draft v3 with POC findings
+test(common): add wrap/unwrap GEK round-trip test
+```
+
+Types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `perf`
+Scope: `hub`, `node`, `common`, or omitted for cross-cutting
+
+## Security rules
+
+- **Never commit private keys** (hub_private.pem, *.key, unlock.key, keystore.enc)
+- **Never commit node_state.json or bob_state.json** (contain private key material)
+- **Never log GEK, private keys, or plaintext passwords** — even at DEBUG level
+- **meshbay.org is internet-facing** — kill all test processes after spikes, close test UFW ports
+
+## Known calibration TODOs
+
+- Argon2id `memory_cost`: currently 65536 (64 MB, 78ms) — increase to 262144 (256 MB) before prod
+  to target ~500ms on typical home server hardware. Implement a `calibrate` CLI command.
+
+## meshbay.org server
+
+- OS: Ubuntu 26.04 LTS, Python 3.14.4
+- SSH: `ssh cbesson@meshbay.org`
+- Web proxy: Caddy (to be installed) behind ports 80/443
+- UFW rules: only 22/tcp, 80/tcp, 443/tcp
+- **Always close test ports after spikes** (`sudo ufw delete allow <port>/<proto>`)
+- Hub POC files: `~/meshbay-poc/` (reference only, not production)