From 1934d12bd1efc949b03cbeee244f0765755a820b Mon Sep 17 00:00:00 2001
From: Operator & Codex <hello@clawdie.si>
Date: Sun, 10 May 2026 18:49:08 +0200
Subject: [PATCH] Clarify public and internal domain defaults (Sam & Claude)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Leave AGENT_DOMAIN blank until a real public DNS name exists, keep home.arpa for internal jail/service names, and mark ZFS as required for Bastille jails.

---
Build: pass
Tests: pass — 59 passed (4 files)

---
Build: pass | Tests: pass — 2372 passed (704 files)
---
 .env.core.example   | 10 +++++++++-
 .env.example        |  9 +++++----
 README.md           |  8 ++++----
 setup/onboarding.ts |  2 +-
 4 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/.env.core.example b/.env.core.example
index fd5b00e..a577aa0 100644
--- a/.env.core.example
+++ b/.env.core.example
@@ -47,7 +47,15 @@ SKILLS_DB_PASSWORD=
 
 # ── Network ──
 AGENT_SUBNET_BASE=10.0.0
-AGENT_DOMAIN=clawdie.invalid
+
+# Domain split:
+# AGENT_DOMAIN          -> public-facing site/API domain. Leave blank until
+#                          you have a real public DNS name configured.
+# AGENT_INTERNAL_DOMAIN -> internal jail/service names written into /etc/hosts
+#
+# Use home.arpa for internal-only names. .local is reserved for mDNS and can
+# create resolver ambiguity on the local link.
+AGENT_DOMAIN=
 AGENT_INTERNAL_DOMAIN=clawdie.home.arpa
 
 # ── Locale (optional — auto-detected on FreeBSD) ──
diff --git a/.env.example b/.env.example
index 6d67aca..208a4ba 100644
--- a/.env.example
+++ b/.env.example
@@ -144,14 +144,15 @@ STRIPE_SECRET_KEY=
 STRIPE_ENABLE_REFUNDS=NO
 
 # Domain split:
-# AGENT_DOMAIN          -> public-facing site/API domain
+# AGENT_DOMAIN          -> public-facing site/API domain. Leave blank until
+#                          you have a real public DNS name configured.
 # AGENT_INTERNAL_DOMAIN -> internal jail/service names written into /etc/hosts
 #
 # Use home.arpa for internal-only names. .local is reserved for mDNS and can
 # create resolver ambiguity on the local link.
-# Use .invalid as the safe placeholder until you set a real public domain.
-# These example values match the default AGENT_NAME above; replace them if you rename the agent.
-AGENT_DOMAIN=clawdie.invalid
+# This example internal value matches the default AGENT_NAME above; replace it
+# if you rename the agent.
+AGENT_DOMAIN=
 AGENT_INTERNAL_DOMAIN=clawdie.home.arpa
 
 # Local code hosting defaults
diff --git a/README.md b/README.md
index 90aef0d..5d39571 100644
--- a/README.md
+++ b/README.md
@@ -357,10 +357,10 @@ Current `main` separates public and internal naming:
 - `AGENT_DOMAIN` is the public-facing site/API domain
 - `AGENT_INTERNAL_DOMAIN` is the internal jail/service zone written into `/etc/hosts`
 
-Fresh installs should use:
+Fresh installs should keep public and internal names separate:
 
-- `AGENT_DOMAIN=home.arpa` for local DNS zone (host uses `<agent>.home.arpa`; replace with a real public domain when ready)
-- `AGENT_INTERNAL_DOMAIN=<agent>.home.arpa`
+- `AGENT_DOMAIN=` until you have a real public DNS name configured
+- `AGENT_INTERNAL_DOMAIN=<agent>.home.arpa` for local jail/service names
 
 Why this changed:
 
@@ -668,7 +668,7 @@ Users then run `/add-slack` on their fork and get clean code that does exactly w
 - FreeBSD 15.x
 - Node.js 24+
 - Python 3.11+ (for voice transcription, screenshots, and other features)
-- ZFS (recommended)
+- ZFS (required for Bastille jails)
 - Optional: Telegram bot token, provider API key, PostgreSQL URLs for memory/skills DB
 
 ## Security
diff --git a/setup/onboarding.ts b/setup/onboarding.ts
index 75c2cda..e0955b7 100644
--- a/setup/onboarding.ts
+++ b/setup/onboarding.ts
@@ -106,7 +106,7 @@ function defaultInternalDomain(): string {
 }
 
 function defaultPublicDomain(): string {
-  return 'home.arpa';
+  return '';
 }
 
 function detectOriginRemote(projectRoot: string): string {