diff --git a/README.md b/README.md
new file mode 100644
index 0000000..71caaa3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# fid
+
+> a fid works knots. this one works tangled's.
+
+the tangled network observatory — every knot, its health, its version, in your terminal.
+
+[tangled](https://tangled.org) is git collaboration built on atproto: anyone can self-host a **knot** (git server) and the network federates. but nobody can *see* the network — how many knots exist, who runs them, which ones are healthy, and which ones are quietly running versions that **silently drop pushes, prs, issues, and invites**. fid is the doctor for that.
+
+<!-- screenshot: fid watch -->
+
+## install
+
+```sh
+# not on npm yet — run from source
+git clone https://tangled.org/@paulvall.dev/fid
+cd fid && pnpm install
+pnpm dev list
+```
+
+## commands
+
+```
+fid list              every knot on the network: repos, version, latency, owner
+fid check <host>      health-check one knot (exit 0 ok / 1 stale / 2 down)
+fid check --mine      check the knots you own
+fid stats             network aggregates: versions, hosting, top knots, growth
+fid repos <host>      what repos live on a knot
+fid spindles          the ci runner fleet
+fid find <query>      search repos across the network
+fid watch             live tui board — scroll, select, probe sweeps every 60s
+```
+
+every command takes `--json` for scripting. `list` takes filters (`--down`, `--stale`, `--managed`, `--self-hosted`) and `--no-repos` to skip the slow repo sweep.
+
+## monitor your knot from cron / ci
+
+`check` exits non-zero when something's wrong, so alerting is one line:
+
+```sh
+# cron: mail me if my knot goes stale or down
+fid check knot.example.com --json > /dev/null || echo "knot unhealthy" | mail -s fid you@example.com
+```
+
+```yaml
+# ci: fail the pipeline if the knot is unhealthy
+- run: npx fid check knot.example.com
+```
+
+exit codes: `0` healthy · `1` reachable but pre-v1.15 (the silent-data-loss cohort) · `2` unreachable.
+
+## how it works
+
+read-only, no auth, no tokens. fid assembles the network from three public sources:
+
+- **the network itself** — verifying a knot writes a `sh.tangled.knot` record to your pds. fid enumerates them all via a relay, then reads each pds. the network is the registry.
+- **direct probes** — each knot gets an xrpc probe (version detection, latency) and a motd fetch. one dead knot never hangs the sweep.
+- **bobbin** — tangled's public api, for search (`fid find`) and profile flavor.
+
+snapshots cache in `~/.cache/fid/` for 5 minutes; `--fresh` skips the cache.
+
+## development
+
+```sh
+pnpm dev <cmd>     # run from source
+pnpm test          # vitest, offline fixtures
+pnpm check         # biome + tsc
+```
+
+`core/` is pure (data in, data out) — the table renderer, the tui, and `--json` all consume the same layer. upstream gaps fid works around are tracked in [UPSTREAM.md](UPSTREAM.md), known rough edges in [ISSUES.md](ISSUES.md).
+
+## why "fid"
+
+a fid is the tapered spike sailors use to work knots — open them, loosen them, splice around them. this one works tangled's.