docs: align README/CONTRIBUTING/GOVERNANCE/docs with LF dual-track positioning

iracic82 · IngmarVG-IB · commit 216bad38ee6e · 2026-05-26T23:14:10.000-07:00
Part B of the LF Onboarding & Repository Alignment plan. Positions this repo as a reference implementation distinct from the IETF specification. Rebased after #136 landed on main; overlapping edits are now no-ops and have been omitted. This commit retains only #104's unique changes: - README.md — add "Relationship to IETF" section; drop the -01 version pin in the opening URL; move the "Why DNS-AID?" comparative content to docs/positioning.md and replace with a brief "Background and Comparison" link section. - SECURITY.md — new "Scope" section delimiting implementation vulns from IETF protocol concerns. - docs/architecture.md — promote the non-normative caveat to a parent "Future Enhancements (Non-Normative)" section (replacing the inline caveat #136 added under one subsection); drop the -01 version pin in the overview sentence. - docs/api-reference.md — verify() wording: "as interpreted by this implementation". - docs/demo-guide.md — opening sentence references the IETF rather than marketing audiences. - docs/positioning.md (new) — non-normative comparative content moved out of README (ANS, .agent gTLD, AgentDNS, NANDA, Web3, ai.txt, Sovereignty Question, Google's Agent Ecosystem). No-ops absorbed by #136 / #138 (omitted from this rebase): CONTRIBUTING.md "Specification Alignment" / "Experimental" sections; GOVERNANCE.md "Scope" section and Ivan→Igor typo fix (#138); docs/api-reference.md "Relationship to IETF" + publish/discover wording; docs/architecture.md Relationship-to-IETF section and Resolution-Priority rename; docs/getting-started.md Relationship-to- IETF section; docs/demo-guide.md first-sentence reframe. Signed-off-by: Ingmar <ivanglabbeek@infoblox.com>
diff --git a/README.md b/README.md
@@ -11,10 +11,18 @@
 
 **DNS-based Agent Identification and Discovery**
 
-Reference implementation of the DNS-AID specification, developed at the IETF: [IETF draft-mozleywilliams-dnsop-dnsaid-01](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/).
+Reference implementation of the DNS-AID specification, developed at the IETF: https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/.
 
 DNS-AID enables AI agents to discover each other via DNS, using the internet's existing naming infrastructure instead of centralized registries or hardcoded URLs.
 
+## Relationship to IETF
+
+The DNS-AID specification is being developed within the IETF: https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/.
+
+This repository provides a reference implementation.
+
+This project does not define the specification. The IETF draft is authoritative.
+
 ## Scope of this Repository
 
 This project focuses on implementation, tooling, and ecosystem activities.
@@ -1015,81 +1023,9 @@ Cloudflare DNS is ideal for demos, workshops, and quick prototyping thanks to it
 - **Simple API**: Well-documented REST API v4
 - **Full DNS-AID compliance**: Supports ServiceMode SVCB with all parameters
 
-## Background: Why DNS-AID?
-
-### vs Competing Proposals
-
-| Approach | Problem | DNS-AID Advantage |
-|----------|---------|-------------------|
-| **ANS (GoDaddy)** | Centralized registry, KYC required, single gatekeeper | Federated — you control your domain, publish instantly |
-| **Google (A2A + UCP)** | Discovery via Gemini/Search, payments via UCP | Neutral discovery — no platform lock-in or transaction fees |
-| **.agent gTLD** | Requires ICANN approval, ongoing domain fees | Works NOW with domains you already own |
-| **AgentDNS (China Telecom)** | Requires 6G infrastructure, carrier control | Works NOW on existing DNS infrastructure |
-| **NANDA (MIT)** | New P2P overlay network, new ops paradigm | Uses infrastructure your DNS team already operates |
-| **Web3 (ERC-8004)** | Gas fees, crypto wallets, enterprise-hostile | Free DNS queries, no blockchain complexity |
-| **ai.txt / llms.txt** | No integrity verification, free-form JSON | DNSSEC cryptographic verification, structured SVCB |
-
-### Feature Comparison
-
-| Feature | DNS-AID | Central Registry | ai.txt |
-|---------|---------|------------------|--------|
-| **Decentralized** | ✅ | ❌ | ✅ |
-| **Secure (DNSSEC)** | ✅ | Varies | ❌ |
-| **Sovereign** | ✅ | ❌ | ✅ |
-| **Standards-based** | ✅ (IETF) | ❌ | ❌ |
-| **Works with existing infra** | ✅ | ❌ | ✅ |
-
-### The Sovereignty Question
-
-> **Who controls agent discovery?**
-> - ANS: GoDaddy (US company as gatekeeper)
-> - AgentDNS: China Telecom (state-owned carrier)
-> - Web3: Ethereum Foundation
-> - **DNS-AID: You control your own domain**
->
-> DNS-AID preserves sovereignty. Organizations and nations maintain control over their own agent namespaces with no central authority that can block, censor, or surveil agent discovery.
-
-### Google's Agent Ecosystem
-
-Google is building a full-stack agent platform: **A2A** (communication), **UCP** (payments), and **Gemini/Search** (discovery). While A2A is an open protocol, discovery through Google surfaces means:
-- Google controls visibility (pay-to-rank)
-- Transaction fees via [UCP](https://developers.google.com/merchant/ucp)
-- Platform dependency for reach
-
-**DNS-AID complements A2A** by providing neutral, decentralized discovery — find agents anywhere, not just through Google.
-
-### Understanding the .agent Domain Approach
-
-The [Agent Community](https://agentcommunity.org/) is pursuing a `.agent` top-level domain through ICANN's [new gTLD program](https://newgtlds.icann.org/). Here's how the two approaches compare:
-
-**How .agent Domains Would Work:**
-1. Apply to ICANN for `.agent` gTLD (~$185,000 application fee)
-2. Wait 9-20 months for ICANN approval process
-3. Build registry infrastructure (Open Agent Registry, Inc.)
-4. Sell `.agent` domains through accredited registrars
-5. Users pay annual registration fees (~$15-50/year per domain)
-
-**How DNS-AID Works:**
-1. Use your existing domain (you already own `yourcompany.com`)
-2. Add DNS-AID records to your zone (`_myagent._mcp._agents.yourcompany.com`)
-3. Start discovering and being discovered immediately
-
-| Factor | .agent gTLD | DNS-AID |
-|--------|-------------|---------|
-| **Cost to publish** | ~$15-50/year domain fee | Free (use existing domain) |
-| **Time to start** | Months (gTLD launch + registration) | Minutes |
-| **Who controls discovery** | Registry operator | You (your domain) |
-| **Works today** | ❌ Pending ICANN approval | ✅ Works now |
-| **Requires new infrastructure** | ✅ Registry, registrars | ❌ Uses existing DNS |
-| **Memorable names** | ✅ `myagent.agent` | `_myagent._mcp._agents.example.com` |
-
-**The Friendly Take:**
-
-Both approaches share the goal of making AI agents discoverable. The `.agent` gTLD creates a dedicated namespace that's easy to remember (`mycompany.agent`), while DNS-AID leverages existing infrastructure so you can start publishing agents today.
-
-DNS-AID doesn't require waiting for ICANN approval or paying for new domains—it works with the DNS infrastructure your organization already operates. If you own `example.com`, you can publish agents to `_myagent._mcp._agents.example.com` right now.
+## Background and Comparison
 
-*Fun fact: When `.agent` domains become available, DNS-AID records will work on them too! The approaches are complementary.*
+For background on how DNS-AID compares to other agent-discovery approaches (ANS, Google A2A+UCP, `.agent` gTLD, AgentDNS, NANDA, Web3, `ai.txt`) and "The Sovereignty Question", see [docs/positioning.md](docs/positioning.md). That content is non-normative — protocol positioning is determined at the IETF.
 
 ## Examples
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,5 +1,11 @@
 # Security Policy
 
+## Scope
+
+This security policy covers vulnerabilities in this reference implementation.
+
+Protocol-level security considerations belong with the IETF draft: https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/.
+
 ## Supported Versions
 
 | Version | Supported          |
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -295,7 +295,7 @@ for agent in result.agents:
 
 ### verify()
 
-Verify DNS-AID records for an agent with security validation.
+Verify DNS-AID records as interpreted by this implementation, with security validation.
 
 ```python
 async def verify(fqdn: str) -> VerifyResult
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-DNS-AID implements the IETF draft-mozleywilliams-dnsop-dnsaid-01 protocol for
+This implementation follows the IETF draft-mozleywilliams-dnsop-dnsaid protocol for
 DNS-based agent discovery. This document covers the key architectural decisions.
 
 ## Relationship to IETF
@@ -192,9 +192,14 @@ that round-trip the same inputs through every surface.
    - Not found → endpoint_source = "http_index_fallback"
 ```
 
-### Future Enhancement: HTTP Index Fallback in DNS Mode
+## Future Enhancements (Non-Normative)
+
 These are implementation proposals and are not part of the current IETF draft.
+
 Items in this section may inform future versions of the specification but should not be treated as authoritative.
+
+### Future Enhancement: HTTP Index Fallback in DNS Mode
+
 Currently the two discovery modes are independent — pure DNS never consults the
 HTTP index and vice versa. Per the DNS-AID draft, the HTTP well-known endpoint
 is a complementary discovery mechanism. A future enhancement should add an
diff --git a/docs/demo-guide.md b/docs/demo-guide.md
@@ -1,6 +1,6 @@
 # DNS-AID Demo Guide
 
-This guide demonstrates use of the DNS-AID reference implementation for agent discovery workflows. Perfect for conference calls, IETF presentations, and Linux Foundation demos.
+This guide demonstrates use of the DNS-AID reference implementation for agent discovery workflows. The underlying specification is developed at the IETF (https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/).
 
 > **Version 0.6.0** - DNSSEC enforcement, DANE full certificate matching, Sigstore release signing, Route53/Cloudflare SVCB param demotion, JWS signatures for application-layer verification, Tier 1 Execution Telemetry SDK, and community rankings.
 
diff --git a/docs/positioning.md b/docs/positioning.md
@@ -0,0 +1,77 @@
+# DNS-AID: Background and Comparison
+
+> **Non-normative.** This document provides background context comparing the DNS-AID approach to other agent-discovery proposals. It describes positioning of the DNS-AID *specification* (developed at the IETF), not features specific to this reference implementation. The authoritative specification is the IETF draft: https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/.
+
+## vs Competing Proposals
+
+| Approach | Problem | DNS-AID Advantage |
+|----------|---------|-------------------|
+| **ANS (GoDaddy)** | Centralized registry, KYC required, single gatekeeper | Federated — you control your domain, publish instantly |
+| **Google (A2A + UCP)** | Discovery via Gemini/Search, payments via UCP | Neutral discovery — no platform lock-in or transaction fees |
+| **.agent gTLD** | Requires ICANN approval, ongoing domain fees | Works NOW with domains you already own |
+| **AgentDNS (China Telecom)** | Requires 6G infrastructure, carrier control | Works NOW on existing DNS infrastructure |
+| **NANDA (MIT)** | New P2P overlay network, new ops paradigm | Uses infrastructure your DNS team already operates |
+| **Web3 (ERC-8004)** | Gas fees, crypto wallets, enterprise-hostile | Free DNS queries, no blockchain complexity |
+| **ai.txt / llms.txt** | No integrity verification, free-form JSON | DNSSEC cryptographic verification, structured SVCB |
+
+## Feature Comparison
+
+| Feature | DNS-AID | Central Registry | ai.txt |
+|---------|---------|------------------|--------|
+| **Decentralized** | ✅ | ❌ | ✅ |
+| **Secure (DNSSEC)** | ✅ | Varies | ❌ |
+| **Sovereign** | ✅ | ❌ | ✅ |
+| **Standards-based** | ✅ (IETF) | ❌ | ❌ |
+| **Works with existing infra** | ✅ | ❌ | ✅ |
+
+## The Sovereignty Question
+
+> **Who controls agent discovery?**
+> - ANS: GoDaddy (US company as gatekeeper)
+> - AgentDNS: China Telecom (state-owned carrier)
+> - Web3: Ethereum Foundation
+> - **DNS-AID: You control your own domain**
+>
+> DNS-AID preserves sovereignty. Organizations and nations maintain control over their own agent namespaces with no central authority that can block, censor, or surveil agent discovery.
+
+## Google's Agent Ecosystem
+
+Google is building a full-stack agent platform: **A2A** (communication), **UCP** (payments), and **Gemini/Search** (discovery). While A2A is an open protocol, discovery through Google surfaces means:
+- Google controls visibility (pay-to-rank)
+- Transaction fees via [UCP](https://developers.google.com/merchant/ucp)
+- Platform dependency for reach
+
+**DNS-AID complements A2A** by providing neutral, decentralized discovery — find agents anywhere, not just through Google.
+
+## Understanding the .agent Domain Approach
+
+The [Agent Community](https://agentcommunity.org/) is pursuing a `.agent` top-level domain through ICANN's [new gTLD program](https://newgtlds.icann.org/). Here's how the two approaches compare:
+
+**How .agent Domains Would Work:**
+1. Apply to ICANN for `.agent` gTLD (~$185,000 application fee)
+2. Wait 9-20 months for ICANN approval process
+3. Build registry infrastructure (Open Agent Registry, Inc.)
+4. Sell `.agent` domains through accredited registrars
+5. Users pay annual registration fees (~$15-50/year per domain)
+
+**How DNS-AID Works:**
+1. Use your existing domain (you already own `yourcompany.com`)
+2. Add DNS-AID records to your zone (`_myagent._mcp._agents.yourcompany.com`)
+3. Start discovering and being discovered immediately
+
+| Factor | .agent gTLD | DNS-AID |
+|--------|-------------|---------|
+| **Cost to publish** | ~$15-50/year domain fee | Free (use existing domain) |
+| **Time to start** | Months (gTLD launch + registration) | Minutes |
+| **Who controls discovery** | Registry operator | You (your domain) |
+| **Works today** | ❌ Pending ICANN approval | ✅ Works now |
+| **Requires new infrastructure** | ✅ Registry, registrars | ❌ Uses existing DNS |
+| **Memorable names** | ✅ `myagent.agent` | `_myagent._mcp._agents.example.com` |
+
+**The Friendly Take:**
+
+Both approaches share the goal of making AI agents discoverable. The `.agent` gTLD creates a dedicated namespace that's easy to remember (`mycompany.agent`), while DNS-AID leverages existing infrastructure so you can start publishing agents today.
+
+DNS-AID doesn't require waiting for ICANN approval or paying for new domains—it works with the DNS infrastructure your organization already operates. If you own `example.com`, you can publish agents to `_myagent._mcp._agents.example.com` right now.
+
+*Fun fact: When `.agent` domains become available, DNS-AID records will work on them too! The approaches are complementary.*
