2026-10-03 18:54:46 +00:00
2 changed files with 111 additions and 0 deletions
@@ -0,0 +1,110 @@
 # 0046: Ekklesia's branding is never forced on an installation
 - Status: Proposed
 - Date: 2026-10-03
 - Related: [ADR 0021](0021-modules-as-hostable-products.md),
  [ADR 0034](0034-host-owned-browser-authentication.md),
  [ADR 0037](0037-host-provided-outbound-email.md),
  [ADR 0038](0038-email-verification-and-password-recovery.md),
  [ADR 0039](0039-shared-design-tokens-and-elements.md),
  [ADR 0043](0043-display-offline-code-fallback.md),
  [ADR 0045](0045-split-dashboard-and-api-origins.md)
 ## Context
 Ekklesia is software a church runs for its own people. The people who use an installation (members,
 visitors, volunteers running a screen) know the church, not the software behind it, and the church
 decides how it presents itself to them. Today the platform names itself in places those people see:
 the sign-in screen asks them to "Sign in to Ekklesia", the Dashboard's heading and page title read
 "Ekklesia", emails ask them to verify "your Ekklesia email address", and an offline screen in the
 sanctuary says it is "waiting for Ekklesia".
 None of those were decided; they accumulated. This records the rule they should have followed, so
 every later screen, message, and module is held to it.
 ## Decision
 ### The principle
 **Ekklesia's branding is never forced on an installation.** Anything a member, visitor, or volunteer
 can see is configurable by the installation and removable entirely. That includes, and is not
 limited to:
 - page titles, headings, and the name of the application in a browser tab, an installed web app, or
  a bookmark;
 - sign-in, verification, recovery, and every other authentication screen;
 - emails: the sender's display name, the subject, and the body;
 - display screens, pairing screens, and offline and failure screens on a display;
 - error pages and error messages a person reads;
 - application names and icons, and any "powered by" or attribution text.
 "Removable entirely" means an installation can show its own name, or no product name at all, and in
 either case no screen or message a person sees names Ekklesia.
 ### What is exempt
 Internal identifiers are not branding and stay as they are: package names, module ids, URL paths
 (`/api/v1/…`, `/assets/ekklesia-dashboard/…`), HTTP header names, environment variable names, cookie
 names, CSS custom property names, element ids and `data-` attributes, storage, cache, and database
 names, and log field names. A person can find them only by opening developer tools or reading
 configuration, and renaming them would break installations for no one's benefit.
 Tooling an operator runs to administer the installation (the command-line tools, Doctor, server logs,
 and startup messages) names the software being operated, as a package name does, and is exempt too.
 So are messages written only for developers: thrown errors that reach a console and never a page, and
 build-time diagnostics for module authors.
 ### How installations configure it
 The platform takes the installation's name from configuration, once, and uses it everywhere a
 person-facing string would otherwise have said "Ekklesia". When no name is configured, the wording is
 neutral ("Sign in", "Verify your email address", "Waiting for the server") rather than falling back to
 "Ekklesia". The default installation therefore names nothing, which is what makes the principle
 checkable: a test can render every person-facing screen and message with no name configured and fail
 on any occurrence of "Ekklesia".
 Browser pages receive the name the way they receive the API origin (ADR 0045): the API renders it
 into the page it serves at startup, so the image stays generic and nothing is decided at build time.
 An email's sender display name is the existing `EKKLESIA_SMTP_FROM_NAME` (ADR 0037); its subject and
 body use the same installation name.
 Visual identity follows the same rule. The platform ships no logo, favicon, or icon today; any it
 ships later must be replaceable by the installation and removable entirely, and must not appear by
 default. Colours and type are the installation's theme (ADR 0039), not a mark.
 ### It applies to modules
 A module's user-visible text follows the same principle. A module that names its host ("Open the
 Ekklesia Dashboard") also ties itself to one host, which ADR 0021 already asks modules not to do.
 Modules refer to the host generically ("the Dashboard") or not at all.
 ## Consequences
 - Every person-facing string that names the platform today becomes either the configured name or
  neutral wording. An implementation slice makes that change and adds the test that keeps it true.
 - New screens, emails, and modules are reviewed against this rule; "Ekklesia" in a person-facing
  string is a defect.
 - Internal identifiers, operator tooling, and developer diagnostics keep the name, so nothing
  operational is renamed.
 - An installation that wants to credit Ekklesia can do so in its own words; the platform never
  inserts that credit.
 ## Alternatives
 - **Keep "Ekklesia" as the default and let installations override it.** Rejected: an installation
  that never thought to configure it would show the software's name to its people, which is forcing
  it by default, and "no occurrence of Ekklesia" could not be tested in the default state.
 - **Rename internal identifiers too.** Rejected: invisible to the people this protects, and costly
  to every installation and module.
 - **A configurable "powered by" line, on by default.** Rejected for the same reason as the first
  alternative.
 - **Per-string customization of every message.** Not needed for this principle: one installation
  name and neutral wording remove the product's name everywhere. Richer copy customization, if
  wanted, is separate work.
 ## Deferred
 - The implementation: the setting, its delivery to pages and emails, the rewording, and the
  regression test.
 - Installation-supplied logos, icons, and favicons, and a web app manifest.
 - Translation and per-string copy customization.
@@ -54,3 +54,4 @@ ADRs capture durable choices that affect more than one package or phase.
 - [0043: The display caches its shell and declared code, and nothing else](0043-display-offline-code-fallback.md) — Accepted
 - [0044: Ekklesia ships one self-hosted reference deployment, composed from pinned sources](0044-self-hosted-reference-deployment.md) — Accepted
 - [0045: The Dashboard and the API may live on separate origins](0045-split-dashboard-and-api-origins.md) — Proposed
 - [0046: Ekklesia's branding is never forced on an installation](0046-installation-owned-branding.md) — Proposed