feat: Official plug API

docs/LOCAL_API.md

@@ -3,7 +3,7 @@
 Parrhesia can run as a normal standalone relay application, but it also exposes a stable
 in-process API for Elixir callers that want to embed the relay inside a larger OTP system.
 
-This document describes that embedding surface. The runtime is still alpha, so treat the API
+This document describes that embedding surface. The runtime is pre-beta, so treat the API
 as usable but not yet frozen.
 
 ## What embedding means today
@@ -14,6 +14,7 @@ Embedding currently means:
 - the host app provides `config :parrhesia, ...` explicitly
 - the host app migrates the Parrhesia database schema
 - callers interact with the relay through `Parrhesia.API.*`
+- host-managed HTTP/WebSocket ingress is mounted through `Parrhesia.Plug`
 
 Current operational assumptions:
 
@@ -63,9 +64,14 @@ config :parrhesia, ecto_repos: [Parrhesia.Repo]
 
 Notes:
 
-- Set `listeners: %{}` if you only want the in-process API and no HTTP/WebSocket ingress.
-- If you do want ingress, copy the listener shape from the config reference in
-  [README.md](../README.md).
+- `listeners: %{}` is the official embedding pattern when your host app owns the HTTPS edge.
+- `listeners: %{}` disables Parrhesia-managed ingress (`/relay`, `/management`, `/metrics`, etc.).
+- Mount `Parrhesia.Plug` from the host app when you still want Parrhesia ingress behind that same
+  HTTPS edge.
+- `Parrhesia.Web.*` modules are internal runtime wiring. Treat `Parrhesia.Plug` as the stable
+  mount API.
+- If you prefer Parrhesia-managed ingress instead, copy the listener shape from the config
+  reference in [README.md](../README.md).
 - Production runtime overrides still use the `PARRHESIA_*` environment variables described in
   [README.md](../README.md).
 
@@ -77,6 +83,27 @@ Parrhesia.Release.migrate()
 
 In development, `mix ecto.migrate -r Parrhesia.Repo` works too.
 
+## Mounting `Parrhesia.Plug` from a host app
+
+When `listeners: %{}` is set, you can still expose Parrhesia ingress by mounting `Parrhesia.Plug`
+in your host endpoint/router and passing an explicit listener config:
+
+```elixir
+forward "/nostr", Parrhesia.Plug,
+  listener: %{
+    id: :public,
+    transport: %{scheme: :https, tls: %{mode: :proxy_terminated}},
+    proxy: %{trusted_cidrs: ["10.0.0.0/8"], honor_x_forwarded_for: true},
+    features: %{
+      nostr: %{enabled: true},
+      admin: %{enabled: true},
+      metrics: %{enabled: true, access: %{private_networks_only: true}}
+    }
+  }
+```
+
+Use the same listener schema documented in [README.md](../README.md).
+
 ## Starting the runtime
 
 In the common case, letting OTP start the `:parrhesia` application is enough.