Document embedded API surface

lib/parrhesia.ex

@@ -1,17 +1,27 @@
 defmodule Parrhesia do
   @moduledoc """
-  Documentation for `Parrhesia`.
+  Parrhesia is a Nostr relay runtime that can run standalone or as an embedded OTP service.
+
+  For embedded use, the main developer-facing surface is `Parrhesia.API.*`.
+  Start with:
+
+  - `Parrhesia.API.Events`
+  - `Parrhesia.API.Stream`
+  - `Parrhesia.API.Admin`
+  - `Parrhesia.API.Identity`
+  - `Parrhesia.API.ACL`
+  - `Parrhesia.API.Sync`
+
+  The host application is responsible for:
+
+  - setting `config :parrhesia, ...`
+  - migrating the configured Parrhesia repos
+  - deciding whether to expose listeners or use only the in-process API
+
+  See `README.md` and `docs/LOCAL_API.md` for the embedding model and configuration guide.
   """
 
-  @doc """
-  Hello world.
-
-  ## Examples
-
-      iex> Parrhesia.hello()
-      :world
-
-  """
+  @doc false
   def hello do
     :world
   end

lib/parrhesia/connection_stats.ex

@@ -1,5 +1,10 @@
 defmodule Parrhesia.ConnectionStats do
-  @moduledoc false
+  @moduledoc """
+  Per-listener connection and subscription counters.
+
+  Tracks active connection and subscription counts per listener and emits
+  `[:parrhesia, :listener, :population]` telemetry events on each change.
+  """
 
   use GenServer
 

lib/parrhesia/postgres_types.ex

@@ -1 +1,4 @@
-Postgrex.Types.define(Parrhesia.PostgresTypes, [], json: JSON)
+Postgrex.Types.define(Parrhesia.PostgresTypes, [],
+  json: JSON,
+  moduledoc: "Custom Postgrex type definitions used by `Parrhesia.Repo` and `Parrhesia.ReadRepo`."
+)

lib/parrhesia/release.ex

@@ -1,10 +1,18 @@
 defmodule Parrhesia.Release do
   @moduledoc """
   Helpers for running Ecto tasks from a production release.
+
+  Intended for use from a release `eval` command where Mix is not available:
+
+      bin/parrhesia eval "Parrhesia.Release.migrate()"
+      bin/parrhesia eval "Parrhesia.Release.rollback(Parrhesia.Repo, 20260101000000)"
   """
 
   @app :parrhesia
 
+  @doc """
+  Runs all pending Ecto migrations for every configured repo.
+  """
   def migrate do
     load_app()
 
@@ -16,6 +24,9 @@ defmodule Parrhesia.Release do
     end
   end
 
+  @doc """
+  Rolls back the given `repo` to the specified migration `version`.
+  """
   def rollback(repo, version) when is_atom(repo) and is_integer(version) do
     load_app()
 

lib/parrhesia/repo.ex

@@ -1,6 +1,9 @@
 defmodule Parrhesia.Repo do
   @moduledoc """
-  PostgreSQL repository for storage adapter persistence.
+  PostgreSQL repository for write traffic and storage adapter persistence.
+
+  Separated from `Parrhesia.ReadRepo` so that ingest writes and read-heavy
+  queries use independent connection pools.
   """
 
   use Ecto.Repo,

lib/parrhesia/runtime.ex

@@ -1,8 +1,25 @@
 defmodule Parrhesia.Runtime do
-  @moduledoc false
+  @moduledoc """
+  Top-level Parrhesia supervisor.
+
+  In normal standalone use, the `:parrhesia` application starts this supervisor automatically.
+  Host applications can also embed it directly under their own supervision tree:
+
+      children = [
+        {Parrhesia.Runtime, name: Parrhesia.Supervisor}
+      ]
+
+  Parrhesia currently assumes a single runtime per BEAM node and uses globally registered
+  process names for core services.
+  """
 
   use Supervisor
 
+  @doc """
+  Starts the Parrhesia runtime supervisor.
+
+  Accepts a `:name` option (defaults to `Parrhesia.Supervisor`).
+  """
   def start_link(opts \\ []) do
     name = Keyword.get(opts, :name, Parrhesia.Supervisor)
     Supervisor.start_link(__MODULE__, opts, name: name)
@@ -13,6 +30,9 @@ defmodule Parrhesia.Runtime do
     Supervisor.init(children(), strategy: :one_for_one)
   end
 
+  @doc """
+  Returns the list of child specifications started by the runtime supervisor.
+  """
   def children do
     [
       Parrhesia.Telemetry,

lib/parrhesia/telemetry.ex

@@ -1,6 +1,10 @@
 defmodule Parrhesia.Telemetry do
   @moduledoc """
   Supervision entrypoint and helpers for relay telemetry.
+
+  Starts the Prometheus reporter and telemetry poller as supervised children.
+  All relay metrics are namespaced under `parrhesia.*` and exposed through the
+  `/metrics` endpoint in Prometheus exposition format.
   """
 
   use Supervisor

lib/parrhesia/web/relay_info.ex

@@ -1,6 +1,10 @@
 defmodule Parrhesia.Web.RelayInfo do
   @moduledoc """
   NIP-11 relay information document.
+
+  `document/1` builds the JSON-serialisable relay info map served on
+  `GET /relay` with `Accept: application/nostr+json`, including supported NIPs,
+  limitations, and the relay's advertised public key.
   """
 
   alias Parrhesia.API.Identity
@@ -8,7 +12,7 @@ defmodule Parrhesia.Web.RelayInfo do
   alias Parrhesia.NIP43
   alias Parrhesia.Web.Listener
 
-  @spec document(Listener.t()) :: map()
+  @spec document(map()) :: map()
   def document(listener) do
     document = %{
       "name" => Metadata.name(),