docs: Update Readme

README.md

@@ -1,2 +1,109 @@
+<p><div style="text-align: center">
+<img src=".gitea/ancient-rome.jpg"
+     alt="Ancient Rome" title="Ancient Rome"
+     width="640" />
+<figcaption>
+Panini, G. P., 1757, <i>Ancient Rome</i> [Oil on canvas].
+The Metropolitan Museum of Art, New York.
+<a href="https://en.wikipedia.org/wiki/Giovanni_Paolo_Panini">Source</a> &mdash; a curated collection of antiquities from one world. Same idea, fewer marble busts.
+</figcaption>
+</div></p>
+
 # obx-pkgs
 
+`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://your.gitea/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 — there is no manifest file to update.
+
+## 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>
+```