build(deploy): assistants.env for the operator's assistants, Caddy forwards /privacy (ADR 0021, step 2)

- deploy/assistants.env.example: every variable commented, with a
  Claude example and a second assistant on the Responses API. The file
  itself is git-ignored and reaches Learn's server alone
  (compose.yaml's env_file, required: false, so an instance without it
  offers no assistant; that syntax needs Docker Compose v2.24 or later).
- deploy/.env.example points to it.
- The Caddyfile forwards /privacy to the web server, as it does
  /simplelogin-callback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

.gitignore

@@ -24,6 +24,8 @@ pubspec_overrides.yaml
 .scloud/
 # Deployment secrets (see deploy/.env.example)
 deploy/.env
+# The assistants and their keys (see deploy/assistants.env.example)
+deploy/assistants.env
 # A sidecar's files on the server, such as Jellyfin's configuration and media
 deploy/jellyfin/
 # Dictionary files an instance loads: made by halkyon_learn_curator, not kept in git.

deploy/.env.example

@@ -31,6 +31,10 @@ DOMAIN=http://localhost
 # it doesn't start with one, as it holds the register.
 #INSTANCE_MEMBERS=
 
+# The instance's assistants, which an operator grants to people (Halkyon Learn's
+# ADR 0021): in a file of their own, deploy/assistants.env, which goes to the server
+# alone (assistants.env.example says how). Without it, no assistant.
+
 # Sidecars switched on beside the instance (sidecars/README.md), each by its compose file
 # after the instance's own: compose.jellyfin.yaml, a Jellyfin people watch and listen to
 # learn from. Unset: the instance alone.

deploy/Caddyfile

@@ -1,6 +1,6 @@
 # Caddy forwards to the API server, and profile pages (ADR 0011), the dictionaries
-# devices download (ADR 0012) and SimpleLogin's forwarding page (ADR 0020) to the web
+# devices download (ADR 0012), SimpleLogin's forwarding page (ADR 0020) and the
-# server (8082), which serves nothing else. Never the calls between the instance's
+# privacy page (ADR 0021) to the web server (8082), which serves nothing else. Never the calls between the instance's
 # services (`/halkyon-base/…`, ADR 0016): they reach each other on its own network. Insights (8081) doesn't run in production;
 # if it is ever re-enabled, reach it through an SSH tunnel, never through this file.
 #
@@ -25,6 +25,13 @@
 		respond 404
 	}
 
+	# The instance's privacy page (Halkyon Learn's ADR 0021, D39), made from its
+	# settings, readable before signing up.
+	@privacy path /privacy
+	handle @privacy {
+		reverse_proxy server:8082
+	}
+
 	# SimpleLogin's forwarding page (ADR 0020): where SimpleLogin sends a sign-in back,
 	# which sends it on to the app that began it, by the loopback or its scheme.
 	@simplelogin path /simplelogin-callback

deploy/assistants.env.example

@@ -0,0 +1,63 @@
+# The instance's assistants (Halkyon Learn's ADR 0021, points 4 and 8, D37 and D38):
+# copy to deploy/assistants.env, restrict it (chmod 600), and fill in. It is git-ignored,
+# goes to Halkyon Learn's server alone (compose.yaml, `env_file`), never into an image,
+# the database or its backups; keep it with deploy/.env's secrets (in Proton Pass).
+# Without the file, the instance offers no assistant, as before. A change takes a
+# restart: docker compose up -d server. Anything the server can't use stops it as it
+# starts, naming the variable.
+#
+# Nobody has an assistant until an operator grants it to them in the app, with limits
+# per day and month; each person agrees once to what goes where. The instance keeps
+# what each person used (requests, tokens, cost) per day for 3 months, never what was
+# asked.
+
+# The assistants' IDs, in the order people see them, by commas or spaces: a letter,
+# then letters, digits or _. Each names its variables below (claude: ASSISTANT_CLAUDE_…)
+# and its grants; renaming one leaves its grants unused.
+ASSISTANTS=claude
+
+# The key the providers' opaque IDs of people are made with (D30): each request carries
+# one, so a provider can act against one person's abuse without blocking the key, and
+# can't tell who it is. At least 32 characters; a new one gives everyone a new ID.
+# Generate: openssl rand -hex 32
+ASSISTANT_ID_KEY=
+
+# The name people see; the ID if unset.
+ASSISTANT_CLAUDE_NAME=Claude Sonnet
+# anthropic (Anthropic's Messages API), openai (OpenAI's chat completions, and every
+# service compatible with them: Mistral, Gemini, OpenRouter, Ollama, vLLM, llama.cpp),
+# or openai-responses (OpenAI's Responses API, which OpenAI's newest models need for
+# tools; Ollama, vLLM and OpenRouter speak it too).
+ASSISTANT_CLAUDE_PROTOCOL=anthropic
+# The provider's address; unset: its own (https://api.anthropic.com, or
+# https://api.openai.com/v1 for both of OpenAI's). With /v1 for the OpenAI protocols
+# (https://api.mistral.ai/v1, https://openrouter.ai/api/v1,
+# https://generativelanguage.googleapis.com/v1beta/openai), without it for Anthropic's.
+# https only, but for a model on this machine or network (http://ollama:11434/v1).
+#ASSISTANT_CLAUDE_BASE_URL=
+ASSISTANT_CLAUDE_MODEL=claude-sonnet-5-5
+# The operator's key at the provider; may be unset only with a BASE_URL of a server of
+# one's own that takes none.
+ASSISTANT_CLAUDE_KEY=
+# on: people may add images (a card's picture, a PDF page) for a model that reads them.
+#ASSISTANT_CLAUDE_IMAGES=on
+# What the model costs per million tokens, as the provider bills it, in
+# ASSISTANT_CURRENCY, with a point for decimals: both or none. With prices, limits and
+# figures are in money; without, in tokens. A change counts from then on; a grant made
+# before prices came or went holds no more until its limits are set again.
+#ASSISTANT_CLAUDE_PRICE_INPUT=3
+#ASSISTANT_CLAUDE_PRICE_OUTPUT=15
+
+# A second one, through OpenAI's Responses API:
+#ASSISTANTS=claude gpt
+#ASSISTANT_GPT_NAME=GPT
+#ASSISTANT_GPT_PROTOCOL=openai-responses
+#ASSISTANT_GPT_MODEL=
+#ASSISTANT_GPT_KEY=
+
+# The currency of the prices (ISO 4217); unset: USD, as the providers bill.
+#ASSISTANT_CURRENCY=USD
+
+# on: people may add their own keys in the app, which then calls their provider
+# directly; the instance sees neither key nor question and counts nothing (D5, D6).
+#ASSISTANT_OWN_KEYS=on

deploy/compose.yaml

@@ -65,6 +65,12 @@ services:
     # no two servers ever migrate at once. (On learn.halkyon.eu, deploy/redeploy.sh has
     # applied them in a run of their own before, so nothing is left to do here.)
     command: ["--apply-migrations"]
+    # The instance's assistants with their keys (Halkyon Learn's ADR 0021, D37), passed
+    # whole, as their variables' names are the IDs the operator chooses; optional, so an
+    # instance without assistants starts as before (assistants.env.example).
+    env_file:
+      - path: assistants.env
+        required: false
     environment:
       SERVERPOD_DATABASE_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in deploy/.env}
       SERVERPOD_PASSWORD_serverSideSessionKeyHashPepper: ${SESSION_KEY_HASH_PEPPER:?set SESSION_KEY_HASH_PEPPER in deploy/.env}