docs(readme): convert README.adoc -> Markdown (renders on Glama/profile/community-health)

README.md

@@ -0,0 +1,130 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+-->
+
+# Overview
+
+The **clade-index** is the central registry for the entire hyperpolymath
+ecosystem. It provides a VeriSimDB-backed taxonomy of 200+ repositories
+organised into 12 clades, with a pointer authority system for tracking
+data ownership, and VCL queries for dashboards, drift detection, and
+work tracking.
+
+**Map and territory**: This registry is the map — queryable,
+presentable, always clean. Repositories are the territory. Editing the
+map never damages the territory.
+
+# Clade Taxonomy
+
+| Code | Clade | Description |
+|----|----|----|
+| `fv` | Formal Verification & Proofs | Provable correctness, reversibility, dependent types |
+| `nl` | Nextgen Languages | Compilers, runtimes, language tooling |
+| `rm` | Repo Management & Tooling | Scaffolding, graph analysis, bot orchestration |
+| `gv` | Governance & Standards | Licensing, compliance, policy enforcement |
+| `db` | Databases | Database engines, query languages |
+| `ap` | Applications | End-user apps, web, desktop, services |
+| `ix` | Infrastructure & Cloud | Containers, deployment, sysadmin |
+| `dx` | Developer Ecosystem | Dev tools, editor integrations, bindings |
+| `pt` | Protocols & Interop | Internet standards, protocol implementations |
+| `ax` | AI & Neurosymbolic | ML, neural proof synthesis, AI governance |
+| `gm` | Games & Interactive | Game engines, interactive experiences |
+| `sc` | Security | Scanning, vulnerability management, access control |
+
+# Structure
+
+    gv-clade-index/
+    ├── 0-AI-MANIFEST.a2ml           # AI agent entry point
+    ├── .machine_readable/           # State, meta, ecosystem, clade declaration
+    ├── verisim/
+    │   ├── config.a2ml              # VeriSimDB instance config
+    │   ├── schema/                  # VCL schemas (7 entity types)
+    │   │   ├── repo.vcl             # Repository octad
+    │   │   ├── clade.vcl            # Clade definition
+    │   │   ├── todo.vcl             # Work items
+    │   │   ├── observation.vcl      # Bot/agent findings
+    │   │   ├── feedback.vcl         # External feedback
+    │   │   ├── lineage.vcl          # Inflate/deflate history
+    │   │   └── forge-identity.vcl   # PK/FK forge mapping
+    │   ├── seed/                    # Initial data
+    │   │   ├── clades.a2ml          # 12 clade definitions
+    │   │   ├── repos.a2ml           # 200 repo registrations
+    │   │   └── forges.a2ml          # Forge account definitions
+    │   └── queries/                 # Pre-built VCL queries
+    │       ├── dashboard.vcl        # Ecosystem overview
+    │       ├── stale.vcl            # Inactive repos
+    │       ├── orphans.vcl          # Unclassified repos
+    │       ├── drift.vcl            # State divergence
+    │       ├── bot-findings.vcl     # Unacknowledged bot observations
+    │       ├── blocked.vcl          # Blocked work items
+    │       ├── cross-clade-deps.vcl # Cross-boundary dependencies
+    │       └── feedback-status.vcl  # Feedback resolution tracking
+    ├── sync/                        # Sync tooling (Phase 2)
+    ├── views/                       # Generated outputs (not committed)
+    └── contractiles/
+        └── must/
+            └── clade-hygiene.a2ml   # Every repo MUST have CLADE.a2ml
+
+# Portal Architecture
+
+    hyperpolymath.github.io          Cloudflare Worker         VeriSimDB (VPS)
+    (ReScript/WASM)            -->   (API Gateway)       -->   (Rust + Elixir)
+                                                                  |
+    Public read --------------------------------------------------> KV snapshot
+    LLM query  ------------------- API key ---------------------> Read-only
+    Contributor ------------------ OAuth -----------------------> Scoped access
+    Bot writes ------------------- Signed JWT ------------------> Write observations
+
+# Identity Model
+
+Every repo has:
+
+- **Primary key**: GitHub (`gh:hyperpolymath/{name}`)
+
+- **Foreign keys**: GitLab, Bitbucket, Codeberg, SourceHut mirrors
+
+- **UUID**: Deterministic v5, derived from
+  `github.com/hyperpolymath/{name}`
+
+- **Clade**: Primary (1) + secondary (0+)
+
+- **Lineage**: standalone, monorepo, monorepo-child, inflated, deflated
+
+# Pointer Authority
+
+Every cached value in VeriSimDB declares its canonical source:
+
+- `pointer` — value lives in the repo (VeriSimDB caches + drift-detects)
+
+- `local` — VeriSimDB owns it (TODOs, bot observations)
+
+- `derived` — computed from other values (clade health scores)
+
+# Contractile System
+
+This repo includes a `clade-hygiene.a2ml` contractile:
+
+- **CLADE-001**: Every repo must have `.machine_readable/CLADE.a2ml`
+
+- **CLADE-002**: CLADE.a2ml must declare a primary clade code
+
+- **CLADE-003**: Primary clade code must be one of the 12 valid codes
+
+# Implementation Phases
+
+| Phase | Deliverable | Status |
+|----|----|----|
+| 0 | Clade taxonomy, repo seed, VCL schema | **Complete** |
+| 1 | Deploy CLADE.a2ml to all 200 repos | Pending |
+| 2 | VeriSimDB instance on VPS | Pending |
+| 3 | Cloudflare Worker API (hardened, tested, CI-gated) | In progress (~60%) |
+| 4 | ReScript/typed-WASM portal | Pending |
+| 5 | LLM query endpoint | Pending |
+| 6 | Bot write endpoints | Pending |
+| 7 | Contributor OAuth | Pending |
+| 8 | Repo lockdown | Pending |
+
+# License
+
+<a href="LICENSE" class="0">MPL-2</a>