Decide: drop DNS from the address — `ken@acme`, not `ken@acme.agentcall.benree.tech`

[KenTaniguchi-R]

Addresses are currently <handle>@<org>.agentcall.benree.tech. This proposes
dropping DNS from the address entirely and making the canonical form
<handle>@<org> — e.g. ken@acme.

Blocked by #154. Not because it can't be done alone, but because #154 already
rewrites address bindings; doing both at once is one migration instead of two.

The DNS suffix is a round trip to nowhere

The org is already a flat, dotless registry label everywhere that matters. We
manufacture a hostname from it and then parse the hostname back into it:

• ORG_RE = /^[a-z0-9][a-z0-9-]{1,62}$/ (packages/shared/src/protocol.ts:4) —
  dots are already forbidden in an org. The org is acme. It was never
  acme.agentcall.benree.tech.
• identityKey(org, handle) (apps/relay/src/tenant.ts:51) — the durable
  identity is already the pair, not a hostname.
• requestOrg (apps/relay/src/tenant.ts:19) exists largely to strip the DNS
  suffix back off what the CLI just glued on.
• config.ts:86 is the glue, and it is a special case for exactly one domain:

  return host === "agentcall.benree.tech" ? `${org}.${host}` : host;

So the pipeline is acme → acme.agentcall.benree.tech → acme. The DNS host
is serialization on top of a registry that already exists.

The address cannot carry routing information anyway

This is the part that settles it. The relay URL lives in the caller's own line
config (cfg.relay), not in the address. And under the
federation non-goal
(#189), a caller only ever reaches their own organization's relay.

There is therefore no case where the address must tell the CLI which host to
resolve. The DNS suffix conveys nothing the config does not already know.

Why the vendor domain is a real problem, not a cosmetic one

benree.tech is a personal umbrella brand. An enterprise buyer reads
ken@acme.agentcall.benree.tech as "our people's identities live under a
vendor's domain."

The distinction that makes this concrete: a vendor domain is fine in a console
URL — acme.slack.com, benree.atlassian.net — because nobody hands those
out. It is not fine in a published identity. Nobody accepts
ken@acme.hey.com as their work email, and AgentCall addresses are handed out
by design, so they inherit the email standard rather than the console standard.

Newest evidence: walking the install/first-call flow as a newcomer, the address
is the single ugliest thing a new user sees, and it appears at the exact moment
they are deciding whether this is a serious product.

	now	proposed
Address	ken@acme.agentcall.benree.tech	ken@acme
Length	30 chars	8

Recommendation

1. ken@acme becomes canonical — for storage, sharing, cards, audit, and
   roster snapshots.
2. agentcall call ken works in-organization, with the org implied by the
   caller's credentials. This is cheap: resolveAddress
   (packages/cli/src/contacts.ts:109) already treats a non-@ argument as a
   contact-book lookup, so it needs only an org-directory fallback behind it.
   Bare handles are an extension, not a phone number — not shareable out of
   band, which is why ken@acme stays canonical.
3. Collapse the hardcoded domain into one constant first. It currently lives
   in apps/relay/src/tenant.ts:4, packages/cli/src/config.ts:33,86, and
   packages/cli/src/contacts.ts:108,117. Unifying those makes the format
   change a near-one-line diff instead of a scavenger hunt, and is worth doing
   whatever this issue decides.

Ruled out

A bare .agentcall suffix (ken@acme.agentcall). Not a resolvable TLD — no
DNS, no public TLS certificate, and owning the real gTLD is a six-figure ICANN
application.

Explicitly out of scope

AGENTCALL_POLICY_EXT = "https://agentcall.benree.tech/ext/policy/v1"
(packages/shared/src/a2a/card.ts:10) is also vendor-branded and appears in
machine surfaces, but it is a namespace identifier — changing it is a protocol
break. Separate decision, lower priority, should not be bundled here.

What this decision needs to settle

• Does ken@acme become canonical, or is the long form kept for out-of-band
  sharing?
• Migration: do existing long-form addresses stay parseable as input
  indefinitely, or for a bounded window?
• Self-hosted deployments already carry SELF_HOSTED_ORG — confirm the flat
  form needs nothing further there.

[KenTaniguchi-R]

Cross-link: #154 already carries a dependency note from #189 making the same
argument — "If the address format changes, do it here" and "the format question
is decided inside the cutover rather than after it."

That note and this issue should not be resolved independently. Treat this issue
as the decision record (code evidence, the ken@acme recommendation, ruled-out
options, open questions) and #154 as where it gets implemented, per its own
requirement of one active address per identity.

If the decision here lands as ken@acme, this issue closes into #154's scope
rather than becoming separate migration work.

[KenTaniguchi-R]

Design options, and an update: agent-call.app is now owned

Filed #310 to move the hosted relay and docs onto it. That does not decide this
issue — #310 decides what the host is, this issue decides whether the host
appears in an address at all — but it changes the economics below, so the
option table is restated honestly rather than as originally filed.

Three findings that shrink this decision

The address string is already presentational. Every frame carries org and
handle as separate structured fields (RecoveryRedeemRequest
protocol.ts:160-161, RecoveryReceipt 171-172). The joined string appears in
exactly one place: RegisterResponse.address (protocol.ts:139). The wire does
not change under any option here.

The gate is one regex. parseAddress (protocol.ts:201-209) requires a
DNS-shaped host — /^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/, a dot and a TLD-like
ending. ken@acme is rejected there and essentially nowhere else.

The org component routes nothing. Under #189 it can only ever be the caller's
own org, determined by their credential. So this is a legibility and trust
decision with near-zero protocol consequence, and should be argued on those
grounds.

Options

Form	Reads as	For	Against
ken@acme	ken, at Acme	Instantly legible; matches the internal model exactly; no host in the identity	Looks like a truncated email; email validators reject it
ken@acme.agent-call.app	a hosted identity	Valid email shape; product-branded, not personally branded; domain already owned	24 chars; hyphen is a dictation tax; still puts a vendor in the identity
acme/ken	a namespace path	No email confusion at all	Less instantly legible; awkward to say aloud
@acme/ken	an npm scope	Developers parse it instantly	Only developers; leading @ breaks in chat clients
ken alone	an extension	Shortest possible	Locally ambiguous (below); not shareable out of band
agent:acme:ken	a URN	Unambiguous, machine-clean	Nobody wants to type this

Now that agent-call.app is owned, row 2 is a real option rather than a
strawman: it reads as "hosted on AgentCall," not "hosted on someone's personal
domain." It still loses on the console-versus-identity distinction — nobody
accepts ken@acme.hey.com as their work email regardless of who owns hey.com —
and the hyphen makes it worse to dictate than to click, which is precisely the
argument for keeping the host in the console and out of the address.

Two tensions worth deciding deliberately

@ buys legibility and implies email. ken@acme needs no explanation, which
is its whole case. But some users will read it as truncated and try to complete
it. acme/ken avoids the problem entirely at the cost of instant legibility.
Arguably the mismatch is a feature — an address that visibly is not an email will
not be mistaken for one — but it should be chosen, not defaulted into because @
looks familiar.

Bare ken is ambiguous locally, even though cross-org routing is impossible.
setup.ts:120-137 is explicit that several relays on one machine are legal —
"that is what lines are for." One machine can therefore hold lines in different
orgs, and agentcall call ken has no single answer there. The ambiguity is
local, not on the wire, so #189 does not resolve it. This argues for ken@acme
canonical, bare ken with documented precedence (contact book, then the primary
line's org directory), and --line as the disambiguator.

Adjacent questions this opens

• Who owns the label acme? A flat namespace has squatting risk. Orgs are
  invite-gated and admin-created so it is controllable, but "first to claim wins"
  needs to be a stated policy once the label is the address.
• Slug versus display name — acme for routing, "Acme Corp" for cards and
  UI. Cheap now, awkward to retrofit.
• Self-hosted label collisions. Two independent deployments both calling
  themselves acme are separate universes until one machine holds a line in
  each. Line names cover it; worth writing down.
• Long-form input window. Accepting the old form as input indefinitely
  costs one regex branch and prevents every "my address broke" report. Recommend
  keeping it permanently rather than bounding it.
• Is there an obvious whoami? After this change the address becomes
  something people ask for by name.

Recommendation

ken@acme canonical; long form accepted as input indefinitely; bare ken with
documented precedence; decided before #154 begins.

The strongest argument is not aesthetics. #154 is a zero-user cutover that fails
if row counts are not zero — so this is the cheapest this decision will ever be,
against a wire that does not move and a four-site change. The window closes
permanently with the first real user.

[KenTaniguchi-R]

Recommendation: ken@acme canonical, ken as caller sugar

Answering the three questions at the bottom of the issue, plus prior art, plus a
finding that changes the architecture this should land on.

The principle

An address should contain only what the customer owns. ken is theirs, acme
is theirs, agentcall.benree.tech is ours. Renaming the vendor domain (#310)
changes which vendor appears; it does not change that one appears.

Prior art: the vendor's domain never appears in an address

Matrix is @ken:acme.com. XMPP is ken@acme.com. SIP is sip:ken@acme.com.
In every one, when a host appears it is the customer's domain. Nobody's
Matrix ID is @ken:acme.matrix.org; nobody's SIP URI is
sip:ken@acme.twilio.com. The vendor's hostname lives in the server endpoint,
which is config — exactly where our cfg.relay already is.

For the short-form half, the well-trodden precedents are PBX extensions (dial
4021 inside the building, +1 415 555 4021 from outside) and Kubernetes DNS
(payments inside the namespace, payments.checkout.svc.cluster.local
qualified). In both, the resolver's context supplies what the short form omits —
here, the caller's credentials supply the org.

Two notes worth recording:

• Matrix deliberately uses : rather than @ so the ID is not mistaken for an
  email address. Our proposed ken@acme gets the same protection for free from
  having no TLD: most linkifiers require a dot-TLD, so it should not auto-link
  as mailto:. Worth confirming in Slack and a terminal before committing.
• Explicitly ruled out: ken@acme.com using the customer's real verified
  domain (DNS TXT, the way Slack and Bluesky verify ownership). It would look
  entirely native and mention us nowhere, but it is almost certainly already
  Ken's email address, and two systems answering the same string is a permanent
  support cost. Naming it here so it is ruled out rather than never considered.

Why @ beats the alternatives

The deciding test is saying it out loud. "Ken at Acme" is typed correctly on the
first try from a hallway conversation, on thirty years of email muscle memory.
acme/ken requires saying a punctuation mark and reads as a repo or a path.
ken:acme is worse to say. Bare @ken is not shareable and is ambiguous in an
audit log spanning tenants.

The three open questions

Canonical vs. long form. ken@acme becomes the only form we emit —
storage, cards, audit, rosters, roster snapshots. ken works as caller sugar
in-organization; resolveAddress (packages/cli/src/contacts.ts:109) already
treats a non-@ argument as a contact-book lookup and needs only an
org-directory fallback behind it.

Migration window. Accept the long form as input indefinitely, never emit
it. It is a suffix strip and one parser branch. A bounded window buys nothing at
zero users and guarantees a broken paste from an old doc in 2027.

Self-hosted. SELF_HOSTED_ORG already carries this. Nothing further.

Say plainly that the address is relay-scoped

ken@acme is unique within a relay, not globally. A self-hosted deployment and
the hosted relay could each mint one and they are different people. That is fine
under the federation non-goal — those two addresses can never meet — but it means
the address cannot double as a durable global identifier. That is the same
distinction #154 draws between stable agent identity and handle address, and it
should be documented rather than left for someone to assume otherwise.

Cap the org length, or this does not actually work

ORG_RE is /^[a-z0-9][a-z0-9-]{1,62}$/ — an org may be 63 characters.
Nothing prevents ken@acme-corporation-platform-engineering, which trades a
vendor domain for a self-inflicted one. The format is only as good as the org
names. Cap at ~20 characters and push short labels at enrollment.

The architecture this should land on

The round trip acme → acme.agentcall.benree.tech → acme is the symptom.
The cause is that the hostname is a second source of truth for the tenant
boundary, and it is already vestigial:

requestOrg (apps/relay/src/tenant.ts:23) reads X-AgentCall-Org first
and only falls back to parsing the subdomain. That header path is already safe,
because authenticatedHandle (apps/relay/src/auth.ts:30) scopes the lookup
WHERE org = ? AND handle = ? — a token from one org cannot authenticate against
another. So the credential already carries the boundary and the DNS layer only
duplicates it. Today a Host/token disagreement resolves correctly by accident
rather than by design.

Proposal — three concerns that are currently fused into one string:

Layer	What it is	Where it lives
Identity	agentId, stable and opaque, survives renames	exists; identityObjectName already keys DOs on it
Address	ken@acme, a display format over (org, handle)	rendered, never parsed for routing
Endpoint	one relay URL	cfg.relay, config only

Which means one host and org from the credential:

• requestOrg loses the hostname branch — header plus deployment-mode guard.
• registrationAddressHost (tenant.ts:71) disappears. Registration returns
  org and handle; the client renders ken@acme.
• relayAddressHost / addressHost (packages/cli/src/config.ts:80-87)
  disappear, and with them the ${org}.${host} special case.
• No wildcard DNS record, no wildcard certificate, no per-org provisioning. One
  custom domain rather than a subdomain per tenant.
• Self-hosted stops being a special case: same path, different base URL.

Further direction, not needed now: bind the org inside the token so
X-AgentCall-Org disappears entirely and the client asserts no context at all.
That is a token-format change and should not be bundled here.

Two corrections to the issue body

Recommendation 3 is already done. The body says the domain is hardcoded at
apps/relay/src/tenant.ts:4, packages/cli/src/config.ts:33,86, and
packages/cli/src/contacts.ts:108,117. All of those now import
HOSTED_RELAY_HOST. The only literal left under src is the constant itself,
packages/shared/src/protocol.ts:14. Same correction applies to #310, whose
"6 files, 10 lines" production surface is now closer to two lines plus the
wrangler.jsonc route.

The status:blocked rationale is weaker than the label. The stated reason is
that #154 already rewrites address bindings, so doing both at once is "one
migration instead of two." At zero users there is no data migration — the same
argument #310 uses to justify doing its breaking change now. What remains is
code-churn overlap in shared files, which is real but is a sequencing preference
rather than a dependency. Given this is the change that actually removes the
vendor domain from published identities — #310 only changes which vendor domain
appears — it is worth deciding whether this can go first or alongside rather than
waiting on a multi-session cutover.

[KenTaniguchi-R]

Follow-up: the address should be a rendering, not a stored string

Correcting and extending my previous comment after reading 0019_agent_identity.sql
and 0020_cards_by_identity.sql, which settle more of this than I had credited.

Already decided by #154 — do not reopen

0019 states it directly: "the address is not part of the identity." Identity
is (org, agent_id); the address is a binding on top of it. 0020 then plans
deliberately for handles to be released and reassigned, moving card, task and
grant ownership onto the stable subject so that reassignment cannot hand the next
ken the previous ken's published policy.

I was going to propose "never reuse handles" as a way to make a shareable address
safe. That is wrong, and it fights a decision that has already been made better:
reuse is allowed, and the hazard is removed by keying ownership to the subject
rather than by freezing the namespace. Recording it here so nobody re-proposes it.

The remaining flaw is composition, not the domain

The address is composed and persisted rather than derived.
registrationAddressHost (apps/relay/src/tenant.ts:71) builds
acme.agentcall.benree.tech at registration and hands it to the client;
requestOrg (tenant.ts:23) parses it back into acme on the way in. That round
trip is the actual defect. Renaming the domain leaves it intact, and leaves a
composed string in every place it has already landed.

Proposal: no composed address is ever stored or transmitted. Storage keeps
(org, handle) and agent_id. The address becomes a pure function of those plus
the context it is being shown in:

render(org, handle, context) -> "ken"       // within the org
                                "ken@acme"  // sharing, rosters, audit, export

One value, two renderings, chosen by where it appears — the PBX-extension and
Kubernetes-DNS pattern from the earlier comment. The consequences:

• Changing the address format later costs one function, not a migration.
• Move the hosted relay and docs off benree.tech to agent-call.app #310's domain change stops touching addresses at all; the host survives only
  as the endpoint in cfg.relay.
• registrationAddressHost and relayAddressHost are deleted rather than
  rewritten. Registration returns org and handle; the client renders.

Two variants: not now, not never

ken@agents.acme.com — a subdomain of the customer's own verified domain.
Zero vendor branding, DNS-verifiable, and it avoids the mailbox collision that
rules out ken@acme.com. It is cosmetically the ideal answer. It is not the
default because it puts a hostname back into the address that carries no routing
meaning, and it makes onboarding require a DNS record — wrong trade for a
developer tool, plausible for a later enterprise tier.

Bare ken as canonical — unshareable, and ambiguous the moment it leaves the
org or lands in a multi-tenant audit view. Better as the in-org rendering of
ken@acme, which the function above already gives us.

The piece this decision still has to carry

Because handles are reassignable by design, ken@acme is a mutable pointer. The
system handles that correctly — durable references key on agent_id. A human
does not get that protection: someone reading ken@acme in an eight-month-old
audit export has no way to know it now resolves to a different person.

So wherever an address is written down for humans to read later — audit exports,
roster snapshots, call history — render the agent id alongside the address
rather than instead of it. Cheap to decide now, awkward to retrofit into exported
records afterwards.

[KenTaniguchi-R]

Revised recommendation: @acme/ken, and the customer-subdomain option is withdrawn

This supersedes the format recommendation in my two comments above. The reasoning
that changed it is worth recording, because it also settles the org-allocation
question I raised and did not answer.

Addresses are keys, not locators

A hostname appears in an address for exactly one reason: federation.
ken@acme.com carries a host because a stranger's mail server has to be told
where to deliver. It is a routing instruction aimed at someone who does not
already know you.

AgentCall has no strangers. Every caller is authenticated to one relay, can only
reach their own organization, and already holds the relay URL in cfg.relay.
Nothing ever resolves an AgentCall address. There is no lookup step for a
hostname to serve.

The codebase has said this all along:

HANDLE_RE = /^[a-z0-9][a-z0-9-]{1,30}$/
ORG_RE    = /^[a-z0-9][a-z0-9-]{1,62}$/

Dots are forbidden in both — neither has ever been able to hold a hostname. And
the comment on HOSTED_RELAY_HOST (packages/shared/src/protocol.ts:5-10) already
says it: "This is deployment configuration, not protocol." The DNS wrapper was
a costume over a key that was already flat.

Withdrawn: ken@agents.acme.com

My earlier comment parked the customer-verified-subdomain form as a possible
enterprise tier. That was wrong at any tier, and I am withdrawing it. A
DNS-shaped address would promise resolution semantics we do not implement.
Someone will eventually dig it, assume it is mailable, or build tooling on the
assumption it resolves. A key that is dressed as a locator is a trap, and the
fact that the domain would belong to the customer rather than to us does not
change that.

Format: @acme/ken

Once the address is understood as a registry key, email shape stops being an
asset and becomes a liability — it is the one shape that misrepresents what the
value is. The npm-scope shape is what a namespaced registry key looks like:

Canonical, shareable	@acme/ken
Inside the organization	ken

Three reasons this beats ken@acme:

1. It is shaped like what it is. A key in a namespace, not an address at a host.
2. The leading @ carries the right signal. Across Slack, GitHub, Discord and
   Twitter it universally reads as "an addressable entity." That is learned
   behaviour we get for free, and ken@acme does not get it.
3. It answers the allocation question by precedent. I raised org allocation
   above without answering it: if acme is a registry key rather than a domain,
   somebody has to allocate it, and ICANN is no longer doing that job for us.
   Choosing the npm shape means we can also borrow npm's answers — scopes are
   first-come within a registry, one organization may hold several, and published
   names are immutable. We do not have to invent this.

The org-length cap from my earlier comment still applies, and matters more here:
ORG_RE permits 63 characters, so @acme-corporation-platform-engineering/ken
is currently legal. Cap it near 20.

Known consequence: CSV escaping in audit exports

A leading @ is a spreadsheet formula prefix. We already defend this —
csvCell (packages/cli/src/commands/audit-export.ts:25):

const text = /^\s*[=+\-@]/.test(raw) ? `'${raw}` : raw;

So it is safe, but the consequence is cosmetic and permanent: every address in
every audit CSV export carries the ' prefix — '@acme/ken. That is the escape
doing its job correctly, and an analyst opening the file will see it on every row.

If that is unacceptable for enterprise exports, acme/ken without the leading
@ keeps the key shape and the GitHub familiarity and is CSV-clean, at the cost
of the entity signal in prose. I would take @acme/ken and live with the
quoting; recording the alternative so the trade is explicit rather than
discovered later.

What actually changes

Less than the format churn suggests, because the grammar was already correct:

• HANDLE_RE and ORG_RE are unchanged.
• Grammar becomes @<org>/<handle>; parsing is strip-@, split-/.
• The in-organization short form stays bare ken.
• resolveAddress (packages/cli/src/contacts.ts:109) currently branches on the
  presence of @ to tell an address from a contact-book name. That becomes a /
  check — one line.
• RegisterResponse (packages/shared/src/protocol.ts:149) is
  { org, token, address }. The address field is the composed string and is
  fully derivable from org + handle; shipping it is what forced
  registrationAddressHost to exist. Delete the field, return org and
  handle, render on the client. See the follow-up comment above on
  address-as-rendering.
• Docs will show @benree/agentcall (a package) beside @acme/ken (a person).
  Same shape, different registry; the surrounding command disambiguates, and the
  shared mental model is arguably a feature.

[KenTaniguchi-R]

Decided: @acme/ken. Recording the decision so this stops being kind:decision
and the label reflects reality.

Settled as recommended above:

• Canonical form @<org>/<handle>; bare ken inside the organization.
• Long form accepted as input indefinitely, never emitted.
• SELF_HOSTED_ORG needs nothing further.
• ORG_RE capped at 20 characters, since the format is only as good as the org names.
• The customer-verified-subdomain variant (ken@agents.acme.com) is withdrawn, not parked.

Spec: docs/superpowers/specs/2026-08-05-address-as-registry-key.md.

One finding that changes the sequencing

packages/shared/src/keys.ts holds a second, independent handle@host
ADDRESS_RE, and the host inside it is load-bearing crypto rather than
decoration:

The relay origin is part of the signed identity so a record published on one
relay cannot be presented as valid on another.

identityTranscript and encryptionKeyTranscript both sign the address.
Removing the host without replacement would make @acme/ken signed on a
self-hosted relay indistinguishable from @acme/ken on the hosted relay, and a
published key record could be replayed across the two.

My earlier comment on this issue called the relay-scoping a documentation matter.
That was wrong — it is a security property with a signature behind it.

The fix is better than the status quo: IdentityRecord and EncryptionKeyRecord
gain an explicit relay_origin field covered by both transcripts, so the binding
is a signed field rather than a substring convention. It breaks transcript shape,
and therefore signatures and the prev chain links between encryption-key epochs
— free at zero users, but a protocol change that gets its own review.

The E2EE envelopes are already fine: HpkeEnvelopeHeader and InnerBase carry
relay_origin explicitly alongside host-shaped from/to, so there the host
is already redundant.

Because the CLI builds envelopes validated by that grammar, the CLI cannot cut
over before the crypto layer does.

Slices

1. Grammar, additive — formatAddress / parseKeyAddress, ORG_RE 63 → 20. Landed.
2. relay_origin as an explicit signed field on both key records. Signature-breaking.
3. Flip the grammar everywhere atomically: keys.ts ADDRESS_RE, envelope from/to,
   RegisterResponse.address, registrationAddressHost, the requestOrg hostname
   branch, and the CLI's addressHost / relayHostWarning / addressTenant.
4. Fixtures and docs.

[KenTaniguchi-R]

Two corrections while implementing, both in the direction of treating this as v1
rather than carrying compatibility for users who do not exist.

The key records stay at v1. Slice 2 bumped IdentityRecord and
EncryptionKeyRecord to v2 on the strength of the rule in keys.ts — "adding a
field means a new record version." That rule protects deployed verifiers, and
there are none. A v2 whose v1 never existed permanently implies an earlier shape
someone might still hold, and it left keys.ts as the only v2 in a protocol
surface that is v1 everywhere else: e2ee payloads, the HPKE AAD, request and
response transcripts, room join proofs. So v1 is this shape, relay_origin
included, and the rule starts applying from here.

The long-form input allowance is withdrawn. The recommendation above said the
handle@host form should be accepted as input indefinitely and never emitted. At
zero users nobody has an old address written down, so that is a compatibility
path with nothing to be compatible with. It was never built: parseAddress
rejects every host-shaped form outright and a test asserts each one fails. The
code was right and this text was stale.

Both are in #333.