diff --git a/README.md b/README.md
index 1aefe41..a7afc85 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,98 @@
-# obx-pkgs
+# Oceanbox Nixpkgs
 
+`obx-pkgs` is the shared Oceanbox Nix overlay. It collects packages that we use
+across projects but that are either not in nixpkgs, are stuck on an outdated
+version, or need internal patches. Each project that consumes the overlay gets
+the same versions, the same fixes, and a single place to update them.
+
+## Usage
+
+### As an overlay on nixpkgs (recommended)
+
+With `npins`:
+
+```nix
+{
+  sources ? import ./npins,
+  pkgs ? import sources.nixpkgs {
+    overlays = [ (import "${sources.obx-pkgs}/overlay.nix") ];
+  },
+}:
+# pkgs.arcosparse, pkgs.openzl, pkgs.sphinx-shibuya-theme, ... are now available
+```
+
+With `flakes`:
+
+```nix
+{
+  inputs.obx-pkgs.url = "git+https://git.oceanbox.io/oceanbox/obx-pkgs";
+
+  outputs = { nixpkgs, obx-pkgs, ... }: {
+    legacyPackages.x86_64-linux = import nixpkgs {
+      system = "x86_64-linux";
+      overlays = [ obx-pkgs.overlays.default ];
+    };
+  };
+}
+```
+
+### As a standalone package set
+
+```nix
+let
+  obx = import sources.obx-pkgs { };
+in
+  [ obx.copernicusmarine obx.sz3 ]
+```
+
+Useful when you want one of our packages without modifying the rest
+of nixpkgs.
+
+## Adding a package
+
+```text
+by-name/
+  <package-name>/
+    default.nix
+```
+
+`default.nix` is a regular `callPackage` function, the same shape you would
+write for nixpkgs:
+
+```nix
+{ stdenv, fetchFromGitHub, ... }:
+stdenv.mkDerivation { ... }
+```
+
+Cross-references between our own packages work via the standard argument syntax
+name the dependency in the argument list (e.g. `arcosparse`) and the overlay's
+`self.callPackage` injects it.
+
+Once the directory exists it is picked up automatically
+
+## Development
+
+```text
+nix-shell
+```
+
+drops you into a shell with `npins`, `nix-init`, `nix-update`, and a
+pre-configured `treefmt`.
+
+Format the tree:
+
+```text
+treefmt
+```
+
+Update a pin:
+
+```text
+npins update nixpkgs
+```
+
+Bump a package version:
+
+```text
+nix-update -f . <package-name>
+```