From b55fa83f325a4f839665a0ae5a94a89fe6effabc Mon Sep 17 00:00:00 2001
From: WellBuilder Admin <admin@wellspr.ing>
Date: Wed, 20 May 2026 02:50:28 +0000
Subject: [PATCH] docs: provision README.md [WellSpr.ing auto]

---
 README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 106 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f55eaf0..83fa3d5 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,108 @@
 # civic-mcp
 
-WellSpr.ing Civic MCP Portal Template & Documentation
\ No newline at end of file
+**WellSpr.ing Civic MCP — Portal Template & Documentation**
+
+> The template repository for all area-code MCP portals in the [WellSpr.ing](https://wellspr.ing) NNN.today network.
+
+This repository documents the schema, tools, governance, and infrastructure pattern used by all 32 (and growing) civic MCP portals. It is the `platform_docs` reference cited in the [federation manifest](https://wellspr.ing/mcp/federation.json).
+
+---
+
+## What is a WellSpr.ing Civic MCP Portal?
+
+Each area-code portal is a [Model Context Protocol](https://modelcontextprotocol.io) server exposing six civic AI tools scoped to a US metro area. Together, the 32 portals form a federated civic AI substrate — independently operable, locally governed, nationally coherent.
+
+## The Six Civic Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_local_news` | Latest civic news for the area |
+| `get_free_items` | Hyperlocal mutual aid free-item exchange |
+| `get_businesses` | Local business directory |
+| `submit_civic_idea` | Civic participation intake — ideas → action |
+| `get_civic_services` | Government services and contact information |
+| `ody_chat` | Covenant-governed conversational civic AI (Ody) |
+
+## File Structure
+
+Each portal repo contains:
+
+```
+mcp-{areacode}/
+├── server.json              # MCP server descriptor (v2 schema)
+├── README.md                # Portal documentation
+├── GOVERNANCE.md            # Covenant governance reference
+├── LICENSE                  # MIT
+├── llms.txt                 # LLM discovery file
+└── .well-known/
+    └── mcp.json             # MCP discovery endpoint
+```
+
+## server.json Schema (v2)
+
+```json
+{
+  "schema_version": "v2",
+  "name": "{areaCode} {city} MCP Server",
+  "area_code": "{areaCode}",
+  "domain": "{areaCode}.today",
+  "mcp_endpoint": "https://{areaCode}.today/mcp",
+  "portal_url": "https://{areaCode}.today",
+  "city": "{primaryCity}",
+  "state": "{state}",
+  "country": "US",
+  "coordinates": { "lat": 0.0, "lng": 0.0 },
+  "tagline": "{civic tagline}",
+  "network": "WellSpr.ing NNN.today",
+  "sovereign_repo": "https://git.wellspr.ing/WellBuilder/mcp-{areaCode}",
+  "federation_url": "https://wellspr.ing/mcp/federation.json",
+  "adjacent": ["{adjacent area codes}"],
+  "tools": [/* see above */],
+  "governance": {
+    "conduct": "https://wellspr.ing/constitution",
+    "vcap": "https://wellspr.ing/vault/ody/attestation-2026-04-17.json",
+    "sovereignty": "https://wellspr.ing/sovereignty",
+    "model": "covenant — freely given, so freely given"
+  },
+  "mirrors": {
+    "primary": "https://git.wellspr.ing/WellBuilder/mcp-{areaCode}",
+    "community": "https://codeberg.org/wellspring/mcp-{areaCode}"
+  }
+}
+```
+
+## Federation Manifest
+
+The canonical index of all portals: [wellspr.ing/mcp/federation.json](https://wellspr.ing/mcp/federation.json)
+
+## Network Traversal
+
+Any MCP-capable agent connected to one portal can traverse the entire network via `get_adjacent_nodes` — hop from 425 (Eastside WA) → 206 (Seattle) → 253 (Tacoma) → 360 (Western WA) without a central directory.
+
+## Governance
+
+All portals operate under the [Eight Principles](https://wellspr.ing/constitution). The WellSpr.ing covenant is non-hierarchical — each portal is locally governed, network-coherent.
+
+VCAP attestation: [wellspr.ing/vault/ody/attestation-2026-04-17.json](https://wellspr.ing/vault/ody/attestation-2026-04-17.json)
+
+## Infrastructure Architecture
+
+```
+Sovereign Primary: git.wellspr.ing/WellBuilder/mcp-{code}   ← source of truth
+  └─push-mirror→ codeberg.org/wellspring/mcp-{code}          ← community discovery
+  └─push-mirror→ github.com/WellBuilder/mcp-{code}          ← commercial discovery (if restored)
+```
+
+See [NotGit.org/formula](https://notgit.org/formula) for the three-mirror architecture.
+
+## Adding a New Portal
+
+1. Fork this template
+2. Update `server.json` with the area code's specifics
+3. Open a pull request at [git.wellspr.ing/wellspring/civic-mcp](https://git.wellspr.ing/wellspring/civic-mcp)
+4. Attest to the [Eight Principles](https://wellspr.ing/constitution)
+
+---
+
+*WellSpr.ing — Civic AI for the commons. Freely given, so freely given.*
+*[wellspr.ing](https://wellspr.ing) · [notgit.org](https://notgit.org) · [noflare.org](https://noflare.org)*