diff --git a/README.md b/README.md
index a122f2e..cb513bf 100644
--- a/README.md
+++ b/README.md
@@ -104,6 +104,19 @@ the container as environment variables. Common options:
   including direct mentions and reviews are delivered. Empty list (default)
   delivers all notifications. Rendered as `HIVE_FORGE_NOTIFY_SKIP_REASONS`
   (comma-separated).
+- **`hyperhive.frontend.dist`** — Override the default frontend package
+  (`pkgs.hyperhive-frontend`, built by `nix/frontend.nix`). Set to a custom
+  derivation to ship a fully custom per-agent SPA. The JSON contract
+  (`/api/state`, `/events/stream`, action endpoints) is the source of truth
+  for any replacement.
+- **`hyperhive.frontend.extraFiles`** — Attrset of extra files/directories
+  to layer on top of the default agent dist. Each entry has a `source` (nix
+  path) and an optional `target` (URL prefix in the static tree, defaults to
+  the attribute name). Example: `{ bitburner.source = ./bitburner-dist; }`
+  serves that dist at `/bitburner/`. Pure additions only — overwriting an
+  existing default file is a hard eval-time error; use `frontend.dist` to
+  replace the whole dist. Paths with leading `/` or `..` segments are
+  rejected at eval time.
 
 See `nix/templates/harness-base.nix` for the full list of options and
 their descriptions.