yakmesh 2.8.2 → 3.0.0

package/CONTRIBUTING.md

@@ -47,6 +47,48 @@ Changes to the timing/oracle layer must:
 
 ---
 
+## 📚 Documentation Guidelines
+
+### Adding New Documentation Pages
+
+When adding new pages to the `docs/` directory:
+
+1. **Update the navigation manifest** in `docs/nav-order.json`:
+   - Add your new page at the appropriate position in the `pages` array
+   - Include: `file`, `icon`, `title`, and `description`
+
+2. **Run the navigation update script**:
+   ```bash
+   node scripts/update-docs-nav.cjs
+   ```
+   This automatically updates prev/next links in all affected pages.
+
+3. **Update the sidebar** in all doc pages:
+   - Add the new page to the sidebar nav list in every `.html` file
+   - Use consistent icon and title
+
+### Navigation Order
+
+The canonical page order is defined in `docs/nav-order.json`. This ensures:
+- Consistent prev/next links across all pages
+- Single source of truth for navigation
+- Easy insertion of new pages without manual link updates
+
+**Example: Adding a new page "DHARMA" between KATHA and VANI**
+
+1. Edit `docs/nav-order.json`:
+   ```json
+   { "file": "katha.html", "icon": "💬", "title": "KATHA", "description": "Rich chat" },
+   { "file": "dharma.html", "icon": "☸️", "title": "DHARMA", "description": "New protocol" },
+   { "file": "vani.html", "icon": "🎙️", "title": "VANI", "description": "Voice calls" },
+   ```
+
+2. Run: `node scripts/update-docs-nav.cjs`
+
+3. This updates KATHA (next→DHARMA), creates correct links in DHARMA, and updates VANI (prev→DHARMA).
+
+---
+
 ## 🏷️ Branding & Trademark
 
 **YAKMESH** is a trademark of the YAKMESH Project (PeerQuanta).

package/Caddyfile

@@ -0,0 +1,77 @@
+# ═══════════════════════════════════════════════════════════════
+# Yakmesh Caddy Configuration — WSS Reverse Proxy
+# ═══════════════════════════════════════════════════════════════
+#
+# Use this Caddyfile to expose your yakmesh node via WSS (HTTPS/WebSocket).
+# Caddy handles automatic TLS via Let's Encrypt and reverse-proxies
+# WebSocket connections to the local yakmesh WS server.
+#
+# SHERPA will advertise this endpoint in beacons, allowing other nodes
+# (even those behind firewalls) to discover and OUTBOUND connect to you.
+#
+# Prerequisites:
+#   1. Domain pointing to this machine (e.g., mesh.yakmesh.dev)
+#   2. Port 443 and 80 accessible (port 80 needed for ACME challenge)
+#   3. Caddy installed: https://caddyserver.com/docs/install
+#
+# Usage:
+#   caddy run --config Caddyfile
+#
+# Set env var so SHERPA advertises this WSS endpoint:
+#   YAKMESH_WS_ENDPOINT=wss://mesh.yakmesh.dev
+#   YAKMESH_SELF_ENDPOINT=https://mesh.yakmesh.dev
+# ═══════════════════════════════════════════════════════════════
+
+# Replace with your domain
+mesh.yakmesh.dev {
+    # WebSocket reverse proxy — mesh peering
+    # Matches WebSocket upgrade requests
+    @websocket {
+        header Connection *Upgrade*
+        header Upgrade websocket
+    }
+    handle @websocket {
+        reverse_proxy localhost:9080
+    }
+
+    # SHERPA beacon — live peer discovery data
+    handle /.well-known/yakmesh/beacon {
+        reverse_proxy localhost:3080
+    }
+
+    # Mesh relay — HTTP message bridge
+    handle /mesh/relay* {
+        reverse_proxy localhost:3080
+    }
+
+    # Health endpoint
+    handle /mesh/health {
+        reverse_proxy localhost:3080/health
+    }
+
+    # Dashboard (optional — remove in production)
+    handle /dashboard* {
+        reverse_proxy localhost:3080
+    }
+
+    # Default: serve documentation
+    handle {
+        reverse_proxy localhost:3080
+    }
+
+    # Logging
+    log {
+        output file /var/log/caddy/yakmesh.log {
+            roll_size 10mb
+            roll_keep 5
+        }
+    }
+
+    # Security headers
+    header {
+        X-Content-Type-Options nosniff
+        X-Frame-Options DENY
+        Referrer-Policy strict-origin-when-cross-origin
+        -Server
+    }
+}

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://yakmesh.dev/assets/yakmesh-logo2.png" alt="YAKMESH" width="200">
 
-  <h1>🏔️ YAKMESH™: Sturdy & Secure</h1>
+  <h1>🏔️ YAKMESH™ v3.0.0 — The Summit Release</h1>
 
   <p><strong>Yielding Atomic Kernel Modular Encryption Secured Hub</strong></p>
 
@@ -10,12 +10,14 @@
     <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-18+-green.svg" alt="Node.js"></a>
     <a href="https://csrc.nist.gov/projects/post-quantum-cryptography"><img src="https://img.shields.io/badge/Crypto-Post--Quantum-blue.svg" alt="Post-Quantum"></a>
     <a href="https://www.npmjs.com/package/yakmesh"><img src="https://img.shields.io/npm/v/yakmesh.svg" alt="npm version"></a>
+    <img src="https://img.shields.io/badge/version-3.0.0-purple.svg" alt="v3.0.0">
+    <img src="https://img.shields.io/badge/Protocol_Layers-30-orange.svg" alt="30-Layer Stack">
   </p>
 </div>
 
 ---
 
-YAKMESH is a high-resiliency, decentralized networking layer designed for the 2026 threat landscape. Built with quantum-resistant cryptography at its core and anchored by PCIe atomic timing synchronization, YAKMESH provides a "sturdy" substrate for distributed systems that cannot afford to fail.
+YAKMESH is a post-quantum secure P2P mesh network with a 30-layer protocol stack, heterogeneous GPU+NPU compute scheduling, and hardware-anchored precision timing. Built for the 2026 threat landscape with NIST FIPS 204/203 cryptography at every layer, YAKMESH provides a "sturdy" substrate for distributed systems that cannot afford to fail.
 
 > **📚 Full documentation: [yakmesh.dev](https://yakmesh.dev)** | **[docs/](docs/)** for specifications
 
@@ -38,29 +40,66 @@ await node.start();
 
 ## Features
 
-- 🔒 **Post-Quantum Secure** - ML-DSA-65 (NIST FIPS 204) signatures
-- 🔮 **TATTVA Oracle** - Self-verifying validation without external trust
-- 🌐 **Mesh Networking** - P2P WebSocket communication with gossip protocol
-- ⏱️ **Precision Timing** - Support for atomic clocks, GPS, PTP, NTP
-- 🧭 **NAMCHE Gateway** - 7-gate mathematical identity verification
-- 🏔️ **SHERPA Discovery** - Decentralized peer discovery
-- 🔐 **ANNEX Channels** - ML-KEM768 encrypted P2P with forward secrecy
-- 🌍 **Geographic Proof** - Speed-of-light exclusion zones
+### Cryptography & Identity
 
-> See [yakmesh.dev](https://yakmesh.dev) for complete feature documentation
+- 🔒 **Post-Quantum Secure** — ML-DSA-65 (FIPS 204) signatures, ML-KEM-768 (FIPS 203) key encapsulation
+- 🧬 **144-Trit Identity** — Ternary identity system with balanced-ternary encoding (YPC-27)
+- 🔐 **ANNEX Channels** — ML-KEM-768 encrypted P2P sessions with forward secrecy (TRIBHUJ ratchet)
+- 🧭 **NAMCHE Gateway** — 7-gate mathematical identity verification
+
+### Networking & Discovery
+
+- 🌐 **Mesh Networking** — P2P WebSocket mesh with epidemic gossip protocol
+- 🏔️ **SHERPA Discovery** — Decentralized peer discovery with DNS beacon broadcast
+- 📦 **NAKPAK Routing** — Efficient binary message routing with checksum verification
+- 💬 **KOMM Stack** — Real-time communication layer (VANI messaging, GUMBA channels, KATHA sessions)
+
+### Validation & Consensus
+
+- 🔮 **TATTVA Oracle** — Self-verifying codebase validation; the code IS the network identity
+- 📜 **DHARMA Consensus** — Multi-phase consensus engine with phase-epoch timing
+- 👁️ **SAKSHI Witness** — Distributed witness protocol for transaction attestation
+- 🌍 **Geographic Proof** — Speed-of-light exclusion zones for physical locality verification
+
+### Compute & Acceleration
+
+- ⚡ **GPU+NPU Acceleration** — Heterogeneous compute via ONNX Runtime (DirectML, CUDA, CPU fallback)
+- 📊 **ComputeScheduler** — Priority-based task scheduling (CRITICAL → HIGH → NORMAL → LOW)
+- 🧠 **SEVA Compute** — Distributed ML inference mesh across network peers
+
+### Security & Monitoring
+
+- 🛡️ **SANGHA Security** — Community-driven threat circulation and collective defense
+- ⏱️ **Precision Timing** — GPS atomic clocks (MA-902), PTP, NTP with sub-millisecond sync
+- 📡 **DARSHAN Telemetry** — Real-time network visibility and diagnostics
+- 🔍 **STEADYWATCH** — Continuous uptime and integrity monitoring
+- ⚖️ **KARMA Rate Limiter** — Behavior-based reputation rate limiting
+
+> See [yakmesh.dev](https://yakmesh.dev) for the complete 30-layer protocol documentation
 
 ## Architecture
 
 ```
-yakmesh/
-├── security/         # NAMCHE gateway, DOKO identity, trust models
-├── oracle/           # TATTVA self-verifying validation engine
-├── mesh/             # SHERPA, NAKPAK, ANNEX networking
+yakmesh-node/
+├── server/           # HTTP/WS server (~3,300 lines), all API routes
+├── security/         # NAMCHE gateway, SANGHA, SAKSHI, trust models, geo-proof
+├── oracle/           # TATTVA validation, consensus engine, code-proof, phase-epoch
+├── identity/         # PQ key management, TRIBHUJ ratchet, 144T identity
+├── mesh/             # SHERPA discovery, NAKPAK routing, ANNEX sessions, pulse-sync
 ├── gossip/           # Epidemic-style message propagation
-├── protocol/         # STUPA, LAMA, MANI, KARMA, MANDALA
-├── adapters/         # Platform integration plugins
-├── embedded-docs/    # GRANTH documentation bundle
-└── server/           # HTTP/WS server
+├── protocol/         # STUPA, LAMA, MANI, KARMA, MANDALA protocol layers
+├── utils/            # Hardware acceleration, ComputeScheduler (GPU+NPU)
+├── cli/              # Command-line interface
+├── dashboard/        # Web-based monitoring UI
+├── database/         # SQLite persistence layer
+├── content/          # Distributed content system
+├── models/           # ONNX ML models for inference
+├── embedded-docs/    # GRANTH documentation bundle (served at /docs)
+├── adapters/         # Platform integration plugins (BYOND, etc.)
+├── templates/        # Configuration templates
+├── launcher/         # Process management and startup
+├── webserver/        # Static web serving
+└── yakbot/           # Bot integration
 ```
 
 ## Network Identity
@@ -78,16 +117,68 @@ import { deriveNetworkName, deriveVerificationPhrase } from 'yakmesh/oracle/netw
 
 Full API documentation at [yakmesh.dev/docs/api](https://yakmesh.dev/docs/api)
 
+### Core
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Node health status |
+| `GET /node` | Node identity info |
+| `GET /peers` | Connected peers |
+| `GET /metrics` | Prometheus-compatible metrics |
+| `GET /dashboard` | Web monitoring UI |
+
+### Oracle & Consensus
+
 | Endpoint | Description |
 |----------|-------------|
-| `/health` | Node health status |
-| `/node` | Node identity info |
-| `/peers` | Connected peers |
-| `/oracle/status` | Oracle integrity check |
-| `/network/identity` | Network identity |
-| `/time/status` | Time source detection |
-| `/security/namche/gates` | Gateway verification status |
-| `/geo/status` | Geographic proof status |
+| `GET /oracle/status` | Oracle integrity check |
+| `GET /oracle/consensus` | Consensus state |
+| `GET /oracle/peers` | Oracle peer list |
+| `POST /oracle/challenge` | Challenge-response verification |
+| `POST /oracle/submit` | Submit oracle data |
+
+### Network & Mesh
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /network/identity` | Network identity |
+| `GET /network/status` | Network state |
+| `GET /network/handshake` | Handshake data |
+| `POST /connect` | Initiate peer connection |
+| `POST /mesh/relay` | Relay message to peers |
+| `GET /gossip` | Gossip state |
+| `GET /discovered` | Discovered nodes |
+
+### Protocol Subsystems
+
+| Endpoint | Description |
+|----------|-------------|
+| `/komm/*` | KOMM real-time communication |
+| `/darshan/*` | DARSHAN network telemetry |
+| `GET /sherpa/status` | SHERPA peer discovery status |
+| `GET /nakpak/status` | NAKPAK routing status |
+| `GET /annex/status` | ANNEX encrypted channel status |
+| `GET /sakshi/status` | SAKSHI witness protocol status |
+| `GET /api/sangha` | SANGHA community security |
+| `/content/*` | Content API |
+
+### Timing & Compute
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /time/status` | Time source detection |
+| `GET /time/capabilities` | Timing hardware capabilities |
+| `GET /api/time` | Full time data |
+| `GET /accel` | Hardware acceleration status |
+| `GET /accel/telemetry` | GPU/NPU telemetry |
+| `GET /scheduler` | ComputeScheduler state |
+| `GET /steadywatch` | Uptime monitoring |
+
+### Security
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /security/namche/gates` | Gateway verification status |
 
 ## License
 
@@ -99,7 +190,7 @@ See [TRADEMARK.md](TRADEMARK.md) for trademark usage policy.
 ---
 
 <div align="center">
-  <sub>Built with quantum principles. Secured by math.</sub>
+  <sub>Built with quantum principles. Secured by math. 30 layers deep.</sub>
   <br><br>
   <strong><a href="https://yakmesh.dev">yakmesh.dev</a></strong>
   <br><br>
@@ -114,4 +205,3 @@ See [TRADEMARK.md](TRADEMARK.md) for trademark usage policy.
   <br>
   <sub>YAKMESH™ is a trademark of PeerQuanta, application pending (Serial No. 99594620).</sub>
 </div>
-

package/adapters/adapter-mlv-bible/README.md

@@ -0,0 +1,124 @@
+# MLV Bible Adapter for Yakmesh
+
+Serve the Modern Literal Version Bible via DARSHAN streaming and enable scripture lookup in KATHA chat.
+
+## Overview
+
+This adapter demonstrates Yakmesh's **anti-censorship ethos** by enabling peer-to-peer scripture distribution without central servers or gatekeepers.
+
+**\\For where two or three are gathered in my name, there am I among them.\\ - Matthew 18:20**
+
+## Features
+
+- **📖 PDF Streaming** - Serve MLV Bible PDFs via DARSHAN (view-not-copy paradigm)
+- **🔍 Scripture Lookup** - Reference parser for all 66 books (e.g., \\John 3:16\\)
+- **💬 Chat Commands** - \\/bible\\, \\/mlv\\, \\/verse\\, \\/scripture\\
+- **🔐 Signed Quotes** - Verifiable scripture cards in chat
+- **🌐 Decentralized** - Each user hosts their own copy
+
+## Installation
+
+\\\javascript
+import { MLVBibleAdapter } from '@yakmesh/adapters/adapter-mlv-bible';
+
+// Create adapter
+const mlv = new MLVBibleAdapter({
+  contentPath: './mlv-content',  // Path to your MLV PDFs
+});
+
+// Initialize
+await mlv.init();
+
+// Register with DARSHAN for streaming
+await mlv.registerWithDarshan(darshan);
+
+// Register with KATHA for chat commands
+mlv.registerWithKatha(katha, chatModRegistry);
+\\\
+
+## Content Setup
+
+1. Download MLV Bible from [modernliteralversion.org](https://www.modernliteralversion.org)
+2. Place PDF files in your content directory
+3. Optionally create a \\erses.json\\ for instant lookup:
+
+\\\json
+{
+  \"John 3:16\": \"For God so loved the world...\",
+  \"Genesis 1:1\": \"In the beginning God created...\"
+}
+\\\
+
+## Chat Commands
+
+| Command | Example | Description |
+|---------|---------|-------------|
+| \\/bible\\ | \\/bible John 3:16\\ | Look up a verse |
+| \\/mlv\\ | \\/mlv Gen 1:1-5\\ | Look up a passage |
+| \\/verse\\ | \\/verse Ps 23:1\\ | Look up a verse |
+| \\/scripture\\ | \\/scripture Rom 8:28\\ | Look up a verse |
+
+## Creating Your Own Scripture Adapter
+
+This adapter serves as a template for other religious texts:
+
+\\\javascript
+import { ContentAdapter, CONTENT_CAPABILITIES } from '../content-adapter.js';
+import { ChatModAdapter, ChatModManifest, CHAT_MOD_CAPABILITIES } from '../chat-mod-adapter.js';
+
+class MyScriptureAdapter extends ContentAdapter {
+  constructor(config) {
+    super({
+      name: 'My Scripture Name',
+      id: 'my-scripture-id',
+      capabilities: [
+        CONTENT_CAPABILITIES.SERVE_PDF,
+        CONTENT_CAPABILITIES.SEARCH_REFERENCE,
+        CONTENT_CAPABILITIES.CHAT_QUOTE,
+      ],
+      ...config,
+    });
+  }
+
+  async lookupReference(reference) {
+    // Parse your reference format
+    // Return { reference, text, ... }
+  }
+}
+\\\
+
+## Security Model
+
+### Capability Declaration
+Adapters MUST declare what they can do upfront:
+- \\SERVE_PDF\\ - Can serve PDF content
+- \\CHAT_QUOTE\\ - Can generate chat quotes
+- \\CMD_SLASH\\ - Can handle slash commands
+
+### Rate Limiting
+Default: 30 messages per minute to prevent spam.
+
+### Signed Responses
+All adapter-generated content includes:
+- Adapter ID and version
+- Manifest hash for verification
+- Timestamp
+
+### No Raw Message Access
+Chat adapters only receive sanitized context based on declared capabilities.
+
+## Philosophy
+
+Yakmesh rejects centralised gatekeeping of religious texts. This adapter embodies:
+
+1. **Host Sovereignty** - You control your content
+2. **No Central Server** - Peer-to-peer distribution
+3. **Anti-Censorship** - No authority can block scripture
+4. **Verification** - Mathematical proof replaces human trust
+
+*\"Let the one who is thirsty come; and let the one who wishes take the free gift of the water of life.\"* - Revelation 22:17
+
+## License
+
+This adapter code is MIT licensed.
+The Modern Literal Version Bible is in the public domain per [modernliteralversion.org](https://www.modernliteralversion.org).