yakmesh 2.8.2 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (232) hide show
  1. package/CHANGELOG.md +637 -0
  2. package/CONTRIBUTING.md +42 -0
  3. package/Caddyfile +77 -0
  4. package/README.md +119 -29
  5. package/adapters/adapter-mlv-bible/README.md +124 -0
  6. package/adapters/adapter-mlv-bible/index.js +400 -0
  7. package/adapters/chat-mod-adapter.js +532 -0
  8. package/adapters/content-adapter.js +273 -0
  9. package/content/api.js +50 -41
  10. package/content/index.js +2 -2
  11. package/content/store.js +355 -173
  12. package/dashboard/index.html +19 -3
  13. package/database/replication.js +117 -37
  14. package/docs/CRYPTO-AGILITY.md +204 -0
  15. package/docs/MTLS-RESEARCH.md +367 -0
  16. package/docs/NAMCHE-SPEC.md +681 -0
  17. package/docs/PEERQUANTA-YAKMESH-INTEGRATION.md +407 -0
  18. package/docs/PRECISION-DISCLOSURE.md +96 -0
  19. package/docs/README.md +76 -0
  20. package/docs/ROADMAP-2.4.0.md +447 -0
  21. package/docs/ROADMAP-2.5.0.md +244 -0
  22. package/docs/SECURITY-AUDIT-REPORT.md +306 -0
  23. package/docs/SST-INTEGRATION.md +712 -0
  24. package/docs/STEADYWATCH-IMPLEMENTATION.md +303 -0
  25. package/docs/TERNARY-AUDIT-REPORT.md +247 -0
  26. package/docs/TME-FAQ.md +221 -0
  27. package/docs/WHITEPAPER.md +623 -0
  28. package/docs/adapters.html +1001 -0
  29. package/docs/advanced-systems.html +1045 -0
  30. package/docs/annex.html +1046 -0
  31. package/docs/api.html +970 -0
  32. package/docs/business/response-templates.md +160 -0
  33. package/docs/c2c.html +1225 -0
  34. package/docs/cli.html +1332 -0
  35. package/docs/configuration.html +1248 -0
  36. package/docs/darshan.html +1085 -0
  37. package/docs/dharma.html +966 -0
  38. package/docs/docs-bundle.html +1075 -0
  39. package/docs/docs.css +3120 -0
  40. package/docs/docs.js +556 -0
  41. package/docs/doko.html +969 -0
  42. package/docs/geo-proof.html +858 -0
  43. package/docs/getting-started.html +840 -0
  44. package/docs/gumba-tutorial.html +1144 -0
  45. package/docs/gumba.html +1098 -0
  46. package/docs/index.html +914 -0
  47. package/docs/jhilke.html +1312 -0
  48. package/docs/karma.html +1100 -0
  49. package/docs/katha.html +1037 -0
  50. package/docs/lama.html +978 -0
  51. package/docs/mandala.html +1067 -0
  52. package/docs/mani.html +964 -0
  53. package/docs/mantra.html +967 -0
  54. package/docs/mesh.html +1409 -0
  55. package/docs/nakpak.html +869 -0
  56. package/docs/namche.html +928 -0
  57. package/docs/nav-order.json +53 -0
  58. package/docs/prahari.html +1043 -0
  59. package/docs/prism-bash.min.js +1 -0
  60. package/docs/prism-javascript.min.js +1 -0
  61. package/docs/prism-json.min.js +1 -0
  62. package/docs/prism-tomorrow.min.css +1 -0
  63. package/docs/prism.min.js +1 -0
  64. package/docs/privacy.html +699 -0
  65. package/docs/quick-reference.html +1181 -0
  66. package/docs/sakshi.html +1402 -0
  67. package/docs/sandboxing.md +386 -0
  68. package/docs/seva.html +911 -0
  69. package/docs/sherpa.html +871 -0
  70. package/docs/studio.html +860 -0
  71. package/docs/stupa.html +995 -0
  72. package/docs/tailwind.min.css +2 -0
  73. package/docs/tattva.html +1332 -0
  74. package/docs/terms.html +686 -0
  75. package/docs/time-server-deployment.md +166 -0
  76. package/docs/time-sources.html +1392 -0
  77. package/docs/tivra.html +1127 -0
  78. package/docs/trademark-policy.html +686 -0
  79. package/docs/tribhuj.html +1183 -0
  80. package/docs/trust-security.html +1029 -0
  81. package/docs/tutorials/backup-recovery.html +654 -0
  82. package/docs/tutorials/dashboard.html +604 -0
  83. package/docs/tutorials/domain-setup.html +605 -0
  84. package/docs/tutorials/host-website.html +456 -0
  85. package/docs/tutorials/mesh-network.html +505 -0
  86. package/docs/tutorials/mobile-access.html +445 -0
  87. package/docs/tutorials/privacy.html +467 -0
  88. package/docs/tutorials/raspberry-pi.html +600 -0
  89. package/docs/tutorials/security-basics.html +539 -0
  90. package/docs/tutorials/share-files.html +431 -0
  91. package/docs/tutorials/troubleshooting.html +637 -0
  92. package/docs/tutorials/trust-karma.html +419 -0
  93. package/docs/tutorials/yak-protocol.html +456 -0
  94. package/docs/tutorials.html +1034 -0
  95. package/docs/vani.html +1270 -0
  96. package/docs/webserver.html +809 -0
  97. package/docs/yak-protocol.html +940 -0
  98. package/docs/yak-timeserver-design.md +475 -0
  99. package/docs/yakapp.html +1015 -0
  100. package/docs/ypc27.html +1069 -0
  101. package/docs/yurt.html +1344 -0
  102. package/embedded-docs/bundle.js +334 -74
  103. package/gossip/protocol.js +247 -27
  104. package/identity/key-resolver.js +262 -0
  105. package/identity/machine-seed.js +632 -0
  106. package/identity/node-key.js +669 -368
  107. package/identity/tribhuj-ratchet.js +506 -0
  108. package/knowledge-base.js +37 -8
  109. package/launcher/yakmesh.bat +62 -0
  110. package/launcher/yakmesh.sh +70 -0
  111. package/mesh/annex.js +462 -108
  112. package/mesh/beacon-broadcast.js +113 -1
  113. package/mesh/darshan.js +1718 -0
  114. package/mesh/gumba.js +1567 -0
  115. package/mesh/jhilke.js +651 -0
  116. package/mesh/katha.js +1012 -0
  117. package/mesh/nakpak-routing.js +8 -5
  118. package/mesh/network.js +724 -34
  119. package/mesh/pulse-sync.js +4 -1
  120. package/mesh/rate-limiter.js +127 -15
  121. package/mesh/seva.js +526 -0
  122. package/mesh/sherpa-discovery.js +89 -8
  123. package/mesh/sybil-defense.js +19 -5
  124. package/mesh/temporal-encoder.js +4 -3
  125. package/mesh/vani.js +1364 -0
  126. package/mesh/yurt.js +1340 -0
  127. package/models/entropy-sentinel.onnx +0 -0
  128. package/models/karma-trust.onnx +0 -0
  129. package/models/manifest.json +43 -0
  130. package/models/sakshi-anomaly.onnx +0 -0
  131. package/oracle/code-proof-protocol.js +7 -6
  132. package/oracle/codebase-lock.js +257 -28
  133. package/oracle/index.js +74 -15
  134. package/oracle/ma902-snmp.js +678 -0
  135. package/oracle/module-sealer.js +5 -3
  136. package/oracle/network-identity.js +16 -0
  137. package/oracle/packet-checksum.js +201 -0
  138. package/oracle/sst.js +579 -0
  139. package/oracle/ternary-144t.js +714 -0
  140. package/oracle/ternary-ml.js +481 -0
  141. package/oracle/time-api.js +239 -0
  142. package/oracle/time-source.js +137 -47
  143. package/oracle/validation-oracle-hardened.js +1111 -1071
  144. package/oracle/validation-oracle.js +4 -2
  145. package/oracle/ypc27.js +211 -0
  146. package/package.json +20 -3
  147. package/protocol/yak-handler.js +35 -9
  148. package/protocol/yak-protocol.js +28 -13
  149. package/reference/cpp/yakmesh_mceliece_shard.cpp +168 -0
  150. package/reference/cpp/yakmesh_ypc27.cpp +179 -0
  151. package/sbom.json +87 -0
  152. package/scripts/security-audit.mjs +264 -0
  153. package/scripts/update-docs-nav.js +194 -0
  154. package/scripts/update-docs-sidebar.cjs +164 -0
  155. package/security/crypto-config.js +4 -3
  156. package/security/dharma-moderation.js +517 -0
  157. package/security/doko-identity.js +193 -143
  158. package/security/domain-consensus.js +86 -85
  159. package/security/fs-hardening.js +620 -0
  160. package/security/hardware-attestation.js +5 -3
  161. package/security/hybrid-trust.js +227 -87
  162. package/security/karma-rate-limiter.js +692 -0
  163. package/security/khata-protocol.js +22 -21
  164. package/security/khata-trust-integration.js +277 -150
  165. package/security/memory-safety.js +635 -0
  166. package/security/mesh-auth.js +11 -10
  167. package/security/mesh-revocation.js +373 -5
  168. package/security/namche-gateway.js +298 -69
  169. package/security/sakshi.js +460 -3
  170. package/security/sangha.js +770 -0
  171. package/security/secure-config.js +473 -0
  172. package/security/silicon-parity.js +13 -10
  173. package/security/steadywatch.js +1142 -0
  174. package/security/strike-system.js +32 -3
  175. package/security/temporal-signing.js +488 -0
  176. package/security/trit-commitment.js +464 -0
  177. package/server/crypto/annex.js +247 -0
  178. package/server/darshan-api.js +343 -0
  179. package/server/index.js +3259 -362
  180. package/server/komm-api.js +668 -0
  181. package/utils/accel.js +2273 -0
  182. package/utils/ternary-id.js +79 -0
  183. package/utils/verify-worker.js +57 -0
  184. package/webserver/index.js +95 -5
  185. package/assets/yakmesh-logo.png +0 -0
  186. package/assets/yakmesh-logo.svg +0 -80
  187. package/assets/yakmesh-logo2.png +0 -0
  188. package/assets/yakmesh-logo2sm.png +0 -0
  189. package/assets/ymsm.png +0 -0
  190. package/website/assets/silhouettes/adapters.svg +0 -107
  191. package/website/assets/silhouettes/api-endpoints.svg +0 -115
  192. package/website/assets/silhouettes/atomic-clock.svg +0 -83
  193. package/website/assets/silhouettes/base-camp.svg +0 -81
  194. package/website/assets/silhouettes/bridge.svg +0 -69
  195. package/website/assets/silhouettes/docs-bundle.svg +0 -113
  196. package/website/assets/silhouettes/doko-basket.svg +0 -70
  197. package/website/assets/silhouettes/fortress.svg +0 -93
  198. package/website/assets/silhouettes/gateway.svg +0 -54
  199. package/website/assets/silhouettes/gears.svg +0 -93
  200. package/website/assets/silhouettes/globe-satellite.svg +0 -67
  201. package/website/assets/silhouettes/karma-wheel.svg +0 -137
  202. package/website/assets/silhouettes/lama-council.svg +0 -141
  203. package/website/assets/silhouettes/mandala-network.svg +0 -169
  204. package/website/assets/silhouettes/mani-stones.svg +0 -149
  205. package/website/assets/silhouettes/mantra-wheel.svg +0 -116
  206. package/website/assets/silhouettes/mesh-nodes.svg +0 -113
  207. package/website/assets/silhouettes/nakpak.svg +0 -56
  208. package/website/assets/silhouettes/peak-lightning.svg +0 -73
  209. package/website/assets/silhouettes/sherpa.svg +0 -69
  210. package/website/assets/silhouettes/stupa-tower.svg +0 -119
  211. package/website/assets/silhouettes/tattva-eye.svg +0 -78
  212. package/website/assets/silhouettes/terminal.svg +0 -74
  213. package/website/assets/silhouettes/webserver.svg +0 -145
  214. package/website/assets/silhouettes/yak.svg +0 -78
  215. package/website/assets/yakmesh-logo.png +0 -0
  216. package/website/assets/yakmesh-logo.webp +0 -0
  217. package/website/assets/yakmesh-logo128x140.webp +0 -0
  218. package/website/assets/yakmesh-logo2.png +0 -0
  219. package/website/assets/yakmesh-logo2.svg +0 -51
  220. package/website/assets/yakmesh-logo40x44.webp +0 -0
  221. package/website/assets/yakmesh.gif +0 -0
  222. package/website/assets/yakmesh.ico +0 -0
  223. package/website/assets/yakmesh.jpg +0 -0
  224. package/website/assets/yakmesh.pdf +0 -0
  225. package/website/assets/yakmesh.png +0 -0
  226. package/website/assets/yakmesh.svg +0 -70
  227. package/website/assets/yakmesh128.webp +0 -0
  228. package/website/assets/yakmesh32.png +0 -0
  229. package/website/assets/yakmesh32.svg +0 -65
  230. package/website/assets/yakmesh32o.ico +0 -2
  231. package/website/assets/yakmesh32o.svg +0 -65
  232. package/website/assets/yakmesh32o.svgz +0 -0
package/docs/tutorials/troubleshooting.html ADDED
@@ -0,0 +1,637 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en" data-theme="tutorials">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <link rel="icon" href="../favicon.ico" sizes="32x32">
7
+ <link rel="icon" href="../icon.svg" type="image/svg+xml">
8
+ <link rel="apple-touch-icon" href="../apple-touch-icon.png">
9
+ <title>Troubleshooting FAQ - YAKMESH Tutorials</title>
10
+ <meta name="description" content="Solutions to common YAKMESH problems - node startup issues, connection problems, dashboard troubleshooting, and more.">
11
+
12
+ <link rel="stylesheet" href="../tailwind.min.css">
13
+ <link rel="stylesheet" href="../prism-tomorrow.min.css">
14
+ <link rel="stylesheet" href="../docs.css">
15
+ <style>
16
+ .theme-accent { color: #10b981; }
17
+ .theme-accent-hover:hover { color: #34d399; }
18
+ .theme-badge { background: rgba(16, 185, 129, 0.2); color: #34d399; }
19
+ .theme-border { border-color: #10b981; }
20
+ .tutorial-card { background: rgba(30, 41, 59, 0.5); border: 1px solid #334155; border-radius: 0.75rem; padding: 1.5rem; margin-bottom: 1.5rem; }
21
+ .tutorial-card:hover { border-color: #10b981; }
22
+ .problem { color: #f87171; font-weight: 600; }
23
+ .solution { color: #34d399; }
24
+ .faq-item { border-left: 3px solid #334155; padding-left: 1rem; margin-bottom: 1.5rem; }
25
+ .faq-item:hover { border-left-color: #10b981; }
26
+ .warning-box { background: rgba(251, 191, 36, 0.1); border: 1px solid #fbbf24; border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
27
+ .tip-box { background: rgba(16, 185, 129, 0.1); border: 1px solid #10b981; border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
28
+ .info-box { background: rgba(59, 130, 246, 0.1); border: 1px solid #3b82f6; border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
29
+ .section-icon { font-size: 2rem; margin-right: 0.75rem; }
30
+ </style>
31
+ </head>
32
+ <body class="bg-mountain-900 text-white min-h-screen">
33
+
34
+ <nav class="docs-sidebar" id="sidebar">
35
+ <a href="../index.html" class="sidebar-logo">
36
+ <span class="logo-icon">🏔️</span>
37
+ <span class="logo-text">Yakmesh</span>
38
+ </a>
39
+ <a href="/dashboard" class="sidebar-dashboard-link"><span>📊</span> <span>Dashboard</span></a>
40
+ <ul class="sidebar-nav">
41
+ <li><a href="../index.html"><span>🏠</span> <span>Overview</span></a></li>
42
+ <li><a href="../getting-started.html"><span>🚀</span> <span>Getting Started</span></a></li>
43
+ <li><a href="../tutorials.html"><span>📖</span> <span>Tutorials</span></a></li>
44
+ <li><a href="../yak-protocol.html"><span class="yak-icon"></span> <span>YAK://</span></a></li>
45
+ <li><a href="../annex.html"><span>🌉</span> <span>ANNEX</span></a></li>
46
+ <li><a href="../nakpak.html"><span>🎒</span> <span>NAKPAK</span></a></li>
47
+ <li><a href="../namche.html"><span>🚪</span> <span>NAMCHE</span></a></li>
48
+ <li><a href="../doko.html"><span>🧺</span> <span>DOKO</span></a></li>
49
+ <li><a href="../sherpa.html"><span>🧗</span> <span>SHERPA</span></a></li>
50
+ <li><a href="../mandala.html"><span>🌐</span> <span>MANDALA</span></a></li>
51
+ <li><a href="../mantra.html"><span>🕉️</span> <span>MANTRA</span></a></li>
52
+ <li><a href="../gumba.html"><span>🛕</span> <span>GUMBA</span></a></li>
53
+ <li><a href="../yurt.html"><span>🏕️</span> <span>YURT</span></a></li>
54
+ <li><a href="../katha.html"><span>💬</span> <span>KATHA</span></a></li>
55
+ <li><a href="../vani.html"><span>🎙️</span> <span>VANI</span></a></li>
56
+ <li><a href="../darshan.html"><span>👁️</span> <span>DARSHAN</span></a></li>
57
+ <li><a href="../stupa.html"><span>🛕</span> <span>STUPA</span></a></li>
58
+ <li><a href="../lama.html"><span>🔮</span> <span>LAMA</span></a></li>
59
+ <li><a href="../mani.html"><span>⏱️</span> <span>MANI</span></a></li>
60
+ <li><a href="../karma.html"><span>☯️</span> <span>KARMA</span></a></li>
61
+ <li><a href="../tattva.html"><span>🔯</span> <span>TATTVA</span></a></li>
62
+ <li><a href="../tribhuj.html"><span>🔺</span> <span>TRIBHUJ</span></a></li>
63
+ <li><a href="../ypc27.html"><span>🔐</span> <span>YPC-27</span></a></li>
64
+ <li><a href="../sakshi.html"><span>👁️</span> <span>SAKSHI</span></a></li>
65
+ <li><a href="../geo-proof.html"><span>🌍</span> <span>PRAMAAN</span></a></li>
66
+ <li><a href="../trust-security.html"><span>🔒</span> <span>SURAKSHA</span></a></li>
67
+ <li><a href="../docs-bundle.html"><span>📚</span> <span>GRANTH</span></a></li>
68
+ <li><a href="../api.html"><span>📡</span> <span>API</span></a></li>
69
+ <li><a href="../adapters.html"><span>🔌</span> <span>Adapters</span></a></li>
70
+ <li><a href="../studio.html"><span>🎨</span> <span>Studio</span></a></li>
71
+ <li><a href="../quick-reference.html"><span>📋</span> <span>Quick Ref</span></a></li>
72
+ </ul>
73
+ </nav>
74
+
75
+ <button class="sidebar-toggle" id="sidebarToggle" title="Toggle sidebar">
76
+ <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor">
77
+ <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 19l-7-7 7-7m8 14l-7-7 7-7" />
78
+ </svg>
79
+ </button>
80
+
81
+ <div class="sidebar-overlay" id="sidebarOverlay"></div>
82
+
83
+ <main class="docs-main" id="mainContent">
84
+ <div class="docs-content">
85
+
86
+ <!-- Breadcrumb -->
87
+ <nav class="mb-6">
88
+ <a href="../tutorials.html" class="text-mountain-400 hover:text-white transition">← Back to Tutorials</a>
89
+ </nav>
90
+
91
+ <!-- Page Header -->
92
+ <div class="mb-8">
93
+ <div class="flex items-center gap-3 mb-2">
94
+ <span class="text-4xl">🩺</span>
95
+ <h1 class="text-4xl font-bold">Troubleshooting FAQ</h1>
96
+ <span class="theme-badge text-xs px-2 py-1 rounded-full">Reference</span>
97
+ </div>
98
+ <p class="theme-accent text-lg">Solutions to common YAKMESH problems</p>
99
+ <p class="text-mountain-300 mt-2">
100
+ Having issues? Find quick solutions to the most common problems here.
101
+ </p>
102
+ </div>
103
+
104
+ <!-- Quick Jump -->
105
+ <div class="tutorial-card">
106
+ <h2 class="text-xl font-bold mb-4">🔗 Quick Navigation</h2>
107
+ <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
108
+ <a href="#node-startup" class="bg-mountain-800 rounded-lg p-3 hover:bg-mountain-700 transition">
109
+ <span class="text-red-400">⚠️</span> Node Won't Start
110
+ </a>
111
+ <a href="#peer-connection" class="bg-mountain-800 rounded-lg p-3 hover:bg-mountain-700 transition">
112
+ <span class="text-red-400">🔌</span> Can't Connect to Peers
113
+ </a>
114
+ <a href="#dashboard" class="bg-mountain-800 rounded-lg p-3 hover:bg-mountain-700 transition">
115
+ <span class="text-red-400">📊</span> Dashboard Not Loading
116
+ </a>
117
+ <a href="#yak-links" class="bg-mountain-800 rounded-lg p-3 hover:bg-mountain-700 transition">
118
+ <span class="text-red-400">🔗</span> yak:// Links Not Working
119
+ </a>
120
+ <a href="#performance" class="bg-mountain-800 rounded-lg p-3 hover:bg-mountain-700 transition">
121
+ <span class="text-red-400">🐌</span> Slow Performance
122
+ </a>
123
+ <a href="#time-sync" class="bg-mountain-800 rounded-lg p-3 hover:bg-mountain-700 transition">
124
+ <span class="text-red-400">⏱️</span> Time Sync Issues
125
+ </a>
126
+ <a href="#getting-help" class="bg-mountain-800 rounded-lg p-3 hover:bg-mountain-700 transition">
127
+ <span class="text-emerald-400">💬</span> Getting Help
128
+ </a>
129
+ </div>
130
+ </div>
131
+
132
+ <!-- Section 1: Node Won't Start -->
133
+ <div class="tutorial-card" id="node-startup">
134
+ <div class="flex items-center mb-4">
135
+ <span class="section-icon">⚠️</span>
136
+ <h2 class="text-2xl font-bold">Node Won't Start</h2>
137
+ </div>
138
+
139
+ <div class="faq-item">
140
+ <p class="problem mb-2">Error: EADDRINUSE - Port already in use</p>
141
+ <p class="solution mb-3">→ Another process is using the port (usually 3000 or 8080)</p>
142
+ <p class="text-mountain-300 mb-3">This happens when you try to start a second instance or a previous instance didn't shut down properly.</p>
143
+
144
+ <h4 class="font-semibold mb-2">Find and kill the process:</h4>
145
+ <pre class="language-bash mb-3"><code># Windows - Find process on port 3000
146
+ netstat -ano | findstr :3000
147
+ # Kill the process (replace 12345 with actual PID)
148
+ taskkill /PID 12345 /F
149
+
150
+ # macOS/Linux - Find and kill in one command
151
+ lsof -ti:3000 | xargs kill -9
152
+
153
+ # Or just use a different port:
154
+ yakmesh start --port 3001</code></pre>
155
+ </div>
156
+
157
+ <div class="faq-item">
158
+ <p class="problem mb-2">Error: Cannot find module '...'</p>
159
+ <p class="solution mb-3">→ Dependencies are missing or corrupted</p>
160
+ <p class="text-mountain-300 mb-3">This usually happens after an incomplete update or a corrupted node_modules folder.</p>
161
+
162
+ <h4 class="font-semibold mb-2">Reinstall dependencies:</h4>
163
+ <pre class="language-bash mb-3"><code># Remove existing node_modules and reinstall
164
+ rm -rf node_modules
165
+ npm install
166
+
167
+ # If that doesn't work, clear npm cache too
168
+ npm cache clean --force
169
+ rm -rf node_modules package-lock.json
170
+ npm install</code></pre>
171
+ </div>
172
+
173
+ <div class="faq-item">
174
+ <p class="problem mb-2">Error: Permission denied (EACCES)</p>
175
+ <p class="solution mb-3">→ File permission issues or need elevated privileges</p>
176
+
177
+ <h4 class="font-semibold mb-2">Windows:</h4>
178
+ <pre class="language-bash mb-3"><code># Run terminal as Administrator
179
+ # Right-click Terminal → Run as Administrator
180
+ yakmesh start</code></pre>
181
+
182
+ <h4 class="font-semibold mb-2">macOS/Linux:</h4>
183
+ <pre class="language-bash mb-3"><code># Fix ownership of the directory
184
+ sudo chown -R $USER:$USER ~/.yakmesh
185
+
186
+ # If binding to port below 1024 (not recommended)
187
+ sudo yakmesh start --port 443</code></pre>
188
+
189
+ <div class="warning-box">
190
+ <p class="text-sm"><strong>⚠️ Avoid running as root</strong> unless absolutely necessary. Instead, use ports above 1024 or fix file permissions.</p>
191
+ </div>
192
+ </div>
193
+ </div>
194
+
195
+ <!-- Section 2: Can't Connect to Peers -->
196
+ <div class="tutorial-card" id="peer-connection">
197
+ <div class="flex items-center mb-4">
198
+ <span class="section-icon">🔌</span>
199
+ <h2 class="text-2xl font-bold">Can't Connect to Peers</h2>
200
+ </div>
201
+
202
+ <div class="faq-item">
203
+ <p class="problem mb-2">0 peers connected / "No peers available"</p>
204
+ <p class="solution mb-3">→ Check your network and firewall settings</p>
205
+
206
+ <h4 class="font-semibold mb-2">1. Check firewall settings:</h4>
207
+ <pre class="language-bash mb-3"><code># Windows - Allow through firewall
208
+ netsh advfirewall firewall add rule name="YAKMESH" dir=in action=allow protocol=TCP localport=8080
209
+ netsh advfirewall firewall add rule name="YAKMESH UDP" dir=in action=allow protocol=UDP localport=8080
210
+
211
+ # Linux (ufw)
212
+ sudo ufw allow 8080/tcp
213
+ sudo ufw allow 8080/udp
214
+
215
+ # macOS - Allow in System Preferences → Security → Firewall → Options</code></pre>
216
+ </div>
217
+
218
+ <div class="faq-item">
219
+ <p class="problem mb-2">Can connect locally but not to internet peers</p>
220
+ <p class="solution mb-3">→ NAT/Router issues - ports may not be forwarded</p>
221
+ <p class="text-mountain-300 mb-3">If you're behind a router, you may need to set up port forwarding or use UPnP.</p>
222
+
223
+ <h4 class="font-semibold mb-2">Options:</h4>
224
+ <ul class="list-disc list-inside text-mountain-300 space-y-2">
225
+ <li><strong>Enable UPnP</strong> in your router settings (automatic port forwarding)</li>
226
+ <li><strong>Manual port forward</strong>: Forward TCP/UDP 8080 to your computer's local IP</li>
227
+ <li><strong>Use NAT traversal</strong>: <code class="bg-mountain-800 px-2 py-1 rounded">yakmesh start --enable-nat-traversal</code></li>
228
+ </ul>
229
+
230
+ <div class="tip-box mt-3">
231
+ <p class="text-sm"><strong>💡 Quick test:</strong> Visit <a href="https://canyouseeme.org" target="_blank" class="theme-accent theme-accent-hover">canyouseeme.org</a> and check if port 8080 is open.</p>
232
+ </div>
233
+ </div>
234
+
235
+ <div class="faq-item">
236
+ <p class="problem mb-2">Bootstrap servers unreachable</p>
237
+ <p class="solution mb-3">→ Network issue or bootstrap servers temporarily down</p>
238
+
239
+ <h4 class="font-semibold mb-2">Test connectivity:</h4>
240
+ <pre class="language-bash mb-3"><code># Test if you can reach bootstrap servers
241
+ ping bootstrap.yakmesh.network
242
+
243
+ # If that fails, check your internet
244
+ ping 8.8.8.8
245
+
246
+ # Try alternative bootstrap servers
247
+ yakmesh start --bootstrap "bootstrap2.yakmesh.network:8080"</code></pre>
248
+
249
+ <p class="text-mountain-300">If bootstrap servers are down, you can still connect by manually adding known peer addresses.</p>
250
+ </div>
251
+ </div>
252
+
253
+ <!-- Section 3: Dashboard Not Loading -->
254
+ <div class="tutorial-card" id="dashboard">
255
+ <div class="flex items-center mb-4">
256
+ <span class="section-icon">📊</span>
257
+ <h2 class="text-2xl font-bold">Dashboard Not Loading</h2>
258
+ </div>
259
+
260
+ <div class="faq-item">
261
+ <p class="problem mb-2">Browser shows "Connection refused" or blank page</p>
262
+ <p class="solution mb-3">→ Server might not be running or wrong address</p>
263
+
264
+ <h4 class="font-semibold mb-2">Check if server is running:</h4>
265
+ <pre class="language-bash mb-3"><code># Check if yakmesh process is running
266
+ # Windows
267
+ tasklist | findstr yakmesh
268
+
269
+ # macOS/Linux
270
+ ps aux | grep yakmesh
271
+
272
+ # Check what's listening on port 3000
273
+ # Windows
274
+ netstat -an | findstr 3000
275
+
276
+ # macOS/Linux
277
+ lsof -i :3000</code></pre>
278
+ </div>
279
+
280
+ <div class="faq-item">
281
+ <p class="problem mb-2">Works with 127.0.0.1 but not localhost (or vice versa)</p>
282
+ <p class="solution mb-3">→ DNS or hosts file issue</p>
283
+ <p class="text-mountain-300 mb-3">Some systems have localhost mapped differently. Try both:</p>
284
+ <ul class="list-disc list-inside text-mountain-300 space-y-1">
285
+ <li><code class="bg-mountain-800 px-2 py-1 rounded">http://localhost:3000/dashboard</code></li>
286
+ <li><code class="bg-mountain-800 px-2 py-1 rounded">http://127.0.0.1:3000/dashboard</code></li>
287
+ </ul>
288
+ </div>
289
+
290
+ <div class="faq-item">
291
+ <p class="problem mb-2">Dashboard looks broken / old version</p>
292
+ <p class="solution mb-3">→ Browser cache issue</p>
293
+
294
+ <h4 class="font-semibold mb-2">Clear cache:</h4>
295
+ <ul class="list-disc list-inside text-mountain-300 space-y-2">
296
+ <li><strong>Hard refresh:</strong> <kbd class="bg-mountain-700 px-2 py-1 rounded">Ctrl+Shift+R</kbd> (Windows/Linux) or <kbd class="bg-mountain-700 px-2 py-1 rounded">Cmd+Shift+R</kbd> (macOS)</li>
297
+ <li><strong>Clear site data:</strong> Open DevTools (F12) → Application → Clear Storage</li>
298
+ <li><strong>Incognito mode:</strong> Try accessing in a private/incognito window</li>
299
+ </ul>
300
+ </div>
301
+
302
+ <div class="faq-item">
303
+ <p class="problem mb-2">Can't access from another device on same network</p>
304
+ <p class="solution mb-3">→ Firewall blocking or wrong binding address</p>
305
+
306
+ <pre class="language-bash mb-3"><code># Start with binding to all interfaces
307
+ yakmesh start --host 0.0.0.0 --port 3000
308
+
309
+ # Then access from other device using your computer's IP:
310
+ # http://192.168.1.100:3000/dashboard</code></pre>
311
+ </div>
312
+ </div>
313
+
314
+ <!-- Section 4: yak:// Links Not Working -->
315
+ <div class="tutorial-card" id="yak-links">
316
+ <div class="flex items-center mb-4">
317
+ <span class="section-icon">🔗</span>
318
+ <h2 class="text-2xl font-bold">yak:// Links Not Working</h2>
319
+ </div>
320
+
321
+ <div class="faq-item">
322
+ <p class="problem mb-2">Browser doesn't recognize yak:// protocol</p>
323
+ <p class="solution mb-3">→ Protocol handler not registered</p>
324
+
325
+ <h4 class="font-semibold mb-2">Register the protocol:</h4>
326
+ <pre class="language-bash mb-3"><code># Run the registration command
327
+ yakmesh register-protocol
328
+
329
+ # Windows: This adds a registry entry
330
+ # macOS: This updates Info.plist handlers
331
+ # Linux: This creates a .desktop file in ~/.local/share/applications</code></pre>
332
+
333
+ <p class="text-mountain-300">You may need to restart your browser after registration.</p>
334
+ </div>
335
+
336
+ <div class="faq-item">
337
+ <p class="problem mb-2">yak:// links open but content doesn't load</p>
338
+ <p class="solution mb-3">→ Node not running or content not available</p>
339
+
340
+ <h4 class="font-semibold mb-2">Checklist:</h4>
341
+ <ul class="list-disc list-inside text-mountain-300 space-y-2">
342
+ <li><strong>Is your node running?</strong> Check the dashboard at <code class="bg-mountain-800 px-1 rounded">localhost:3000</code></li>
343
+ <li><strong>Are you connected to peers?</strong> You need peers to find content</li>
344
+ <li><strong>Is the content still available?</strong> Content may have expired or been removed</li>
345
+ <li><strong>Check content hash:</strong> Verify the hash in the URL is correct</li>
346
+ </ul>
347
+ </div>
348
+
349
+ <div class="faq-item">
350
+ <p class="problem mb-2">"Content not found on mesh"</p>
351
+ <p class="solution mb-3">→ No peers have the content cached</p>
352
+ <p class="text-mountain-300 mb-3">Content on the mesh is distributed - if no one has it cached, it won't be available.</p>
353
+
354
+ <div class="info-box">
355
+ <p class="text-sm"><strong>ℹ️ How YAKMESH content works:</strong> Content is stored across the network.
356
+ If the original uploader and all seeders go offline, content becomes unavailable until someone
357
+ with a copy comes back online.</p>
358
+ </div>
359
+ </div>
360
+ </div>
361
+
362
+ <!-- Section 5: Slow Performance -->
363
+ <div class="tutorial-card" id="performance">
364
+ <div class="flex items-center mb-4">
365
+ <span class="section-icon">🐌</span>
366
+ <h2 class="text-2xl font-bold">Slow Performance</h2>
367
+ </div>
368
+
369
+ <div class="faq-item">
370
+ <p class="problem mb-2">Downloads are very slow</p>
371
+ <p class="solution mb-3">→ Check peer count - need enough good peers</p>
372
+
373
+ <h4 class="font-semibold mb-2">Check peer status:</h4>
374
+ <pre class="language-bash mb-3"><code># View connected peers
375
+ yakmesh peers list
376
+
377
+ # Check peer quality scores
378
+ yakmesh peers stats
379
+
380
+ # Optimal range: 10-50 peers
381
+ # Too few = slow downloads
382
+ # Too many = connection overhead</code></pre>
383
+ </div>
384
+
385
+ <div class="faq-item">
386
+ <p class="problem mb-2">High CPU usage</p>
387
+ <p class="solution mb-3">→ Too many operations or verification backlog</p>
388
+
389
+ <h4 class="font-semibold mb-2">Reduce load:</h4>
390
+ <pre class="language-bash mb-3"><code># Limit concurrent operations
391
+ yakmesh config set max-concurrent-downloads 3
392
+ yakmesh config set max-concurrent-uploads 3
393
+
394
+ # Reduce verification intensity
395
+ yakmesh config set verification-threads 2
396
+
397
+ # Check what's consuming resources
398
+ yakmesh status --verbose</code></pre>
399
+ </div>
400
+
401
+ <div class="faq-item">
402
+ <p class="problem mb-2">Running out of disk space</p>
403
+ <p class="solution mb-3">→ Cache and stored content building up</p>
404
+
405
+ <h4 class="font-semibold mb-2">Clean up storage:</h4>
406
+ <pre class="language-bash mb-3"><code># Check storage usage
407
+ yakmesh storage stats
408
+
409
+ # Clear cache (won't delete your files)
410
+ yakmesh cache clear
411
+
412
+ # Set cache size limit
413
+ yakmesh config set cache-size-limit 5GB
414
+
415
+ # Clean old content
416
+ yakmesh storage prune --older-than 30d</code></pre>
417
+ </div>
418
+
419
+ <div class="faq-item">
420
+ <p class="problem mb-2">Network congestion / bandwidth issues</p>
421
+ <p class="solution mb-3">→ Set upload/download limits</p>
422
+
423
+ <pre class="language-bash mb-3"><code># Limit bandwidth usage
424
+ yakmesh config set max-upload-rate 10MB
425
+ yakmesh config set max-download-rate 50MB
426
+
427
+ # Schedule heavy operations for off-peak hours
428
+ yakmesh config set quiet-hours "02:00-06:00"</code></pre>
429
+ </div>
430
+ </div>
431
+
432
+ <!-- Section 6: Time Sync Issues -->
433
+ <div class="tutorial-card" id="time-sync">
434
+ <div class="flex items-center mb-4">
435
+ <span class="section-icon">⏱️</span>
436
+ <h2 class="text-2xl font-bold">Time Sync Issues</h2>
437
+ </div>
438
+
439
+ <div class="faq-item">
440
+ <p class="problem mb-2">Warning: Clock drift detected / MANI time sync failed</p>
441
+ <p class="solution mb-3">→ System clock is out of sync with network time</p>
442
+ <p class="text-mountain-300 mb-3">YAKMESH uses the MANI time synchronization system which is critical for content verification and consensus.</p>
443
+
444
+ <h4 class="font-semibold mb-2">Sync your system clock:</h4>
445
+ <pre class="language-bash mb-3"><code># Windows - Sync with internet time
446
+ w32tm /resync /force
447
+
448
+ # macOS - Enable automatic time
449
+ sudo sntp -sS time.apple.com
450
+
451
+ # Linux - Use systemd-timesyncd or chrony
452
+ sudo timedatectl set-ntp true
453
+ sudo systemctl restart systemd-timesyncd</code></pre>
454
+ </div>
455
+
456
+ <div class="faq-item">
457
+ <p class="problem mb-2">MANI can't reach time sources</p>
458
+ <p class="solution mb-3">→ Firewall blocking NTP or mesh time servers</p>
459
+
460
+ <h4 class="font-semibold mb-2">Allow NTP traffic:</h4>
461
+ <pre class="language-bash mb-3"><code># Windows
462
+ netsh advfirewall firewall add rule name="NTP" dir=out action=allow protocol=UDP remoteport=123
463
+
464
+ # Linux
465
+ sudo ufw allow out 123/udp
466
+
467
+ # Test NTP connectivity
468
+ ntpdate -q pool.ntp.org</code></pre>
469
+
470
+ <div class="tip-box">
471
+ <p class="text-sm"><strong>💡 Tip:</strong> MANI uses multiple time sources including NTP servers and mesh peer consensus.
472
+ If external NTP is blocked, it can still sync from trusted peers.</p>
473
+ </div>
474
+ </div>
475
+
476
+ <div class="faq-item">
477
+ <p class="problem mb-2">Conflicts with other NTP software</p>
478
+ <p class="solution mb-3">→ Multiple time sync services running</p>
479
+ <p class="text-mountain-300 mb-3">If you have other NTP clients (like chrony, ntpd), they may conflict with MANI.</p>
480
+
481
+ <pre class="language-bash mb-3"><code># Check what's managing time
482
+ timedatectl status
483
+
484
+ # Disable conflicting service (example)
485
+ sudo systemctl stop ntpd
486
+ sudo systemctl disable ntpd
487
+
488
+ # Let MANI handle time sync
489
+ yakmesh config set mani-time-sync enabled</code></pre>
490
+ </div>
491
+ </div>
492
+
493
+ <!-- Section 7: Getting Help -->
494
+ <div class="tutorial-card" id="getting-help">
495
+ <div class="flex items-center mb-4">
496
+ <span class="section-icon">💬</span>
497
+ <h2 class="text-2xl font-bold">Getting Help</h2>
498
+ </div>
499
+
500
+ <div class="faq-item">
501
+ <p class="text-lg mb-3 theme-accent font-semibold">Enable Debug Mode</p>
502
+ <p class="text-mountain-300 mb-3">Debug mode provides detailed logging to help diagnose issues:</p>
503
+
504
+ <pre class="language-bash mb-3"><code># Start with debug output
505
+ yakmesh start --debug
506
+
507
+ # Or enable debug for specific module
508
+ yakmesh start --debug=network
509
+ yakmesh start --debug=storage
510
+ yakmesh start --debug=mani
511
+
512
+ # Save debug output to file
513
+ yakmesh start --debug > yakmesh-debug.log 2>&1</code></pre>
514
+ </div>
515
+
516
+ <div class="faq-item">
517
+ <p class="text-lg mb-3 theme-accent font-semibold">Log File Locations</p>
518
+ <div class="bg-mountain-800 rounded-lg p-4 font-mono text-sm space-y-2">
519
+ <div><span class="text-blue-400">Windows:</span> <span class="text-gray-300">%APPDATA%\yakmesh\logs\</span></div>
520
+ <div><span class="text-blue-400">macOS:</span> <span class="text-gray-300">~/Library/Logs/yakmesh/</span></div>
521
+ <div><span class="text-blue-400">Linux:</span> <span class="text-gray-300">~/.yakmesh/logs/</span></div>
522
+ </div>
523
+
524
+ <pre class="language-bash mt-3"><code># Open logs folder
525
+ yakmesh logs --open
526
+
527
+ # View recent logs
528
+ yakmesh logs --tail 100
529
+
530
+ # Search logs for errors
531
+ yakmesh logs --grep "ERROR"</code></pre>
532
+ </div>
533
+
534
+ <div class="faq-item">
535
+ <p class="text-lg mb-3 theme-accent font-semibold">Report Issues on GitHub</p>
536
+ <p class="text-mountain-300 mb-3">Found a bug or have a feature request? Open an issue on GitHub:</p>
537
+
538
+ <a href="https://github.com/yakmesh/yakmesh-node/issues" target="_blank"
539
+ class="inline-flex items-center gap-2 bg-mountain-800 hover:bg-mountain-700 px-4 py-2 rounded-lg transition">
540
+ <svg class="w-5 h-5" fill="currentColor" viewBox="0 0 24 24"><path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0024 12c0-6.63-5.37-12-12-12z"/></svg>
541
+ Open GitHub Issues
542
+ </a>
543
+
544
+ <div class="info-box mt-4">
545
+ <p class="text-sm"><strong>ℹ️ When reporting issues, include:</strong></p>
546
+ <ul class="list-disc list-inside text-sm text-mountain-300 mt-2 space-y-1">
547
+ <li>YAKMESH version (<code class="bg-mountain-800 px-1 rounded">yakmesh --version</code>)</li>
548
+ <li>Operating system and version</li>
549
+ <li>Steps to reproduce the problem</li>
550
+ <li>Relevant log output (sanitize any private data)</li>
551
+ </ul>
552
+ </div>
553
+ </div>
554
+
555
+ <div class="faq-item">
556
+ <p class="text-lg mb-3 theme-accent font-semibold">Community Resources</p>
557
+ <div class="grid grid-cols-1 sm:grid-cols-2 gap-3">
558
+ <a href="#" class="flex items-center gap-3 bg-mountain-800 hover:bg-mountain-700 p-3 rounded-lg transition">
559
+ <span class="text-2xl">💬</span>
560
+ <div>
561
+ <div class="font-semibold">Discord</div>
562
+ <div class="text-sm text-mountain-400">Real-time community chat</div>
563
+ </div>
564
+ </a>
565
+ <a href="#" class="flex items-center gap-3 bg-mountain-800 hover:bg-mountain-700 p-3 rounded-lg transition">
566
+ <span class="text-2xl">📣</span>
567
+ <div>
568
+ <div class="font-semibold">Telegram</div>
569
+ <div class="text-sm text-mountain-400">Updates and announcements</div>
570
+ </div>
571
+ </a>
572
+ <a href="#" class="flex items-center gap-3 bg-mountain-800 hover:bg-mountain-700 p-3 rounded-lg transition">
573
+ <span class="text-2xl">🐦</span>
574
+ <div>
575
+ <div class="font-semibold">Twitter/X</div>
576
+ <div class="text-sm text-mountain-400">@yakmesh</div>
577
+ </div>
578
+ </a>
579
+ <a href="#" class="flex items-center gap-3 bg-mountain-800 hover:bg-mountain-700 p-3 rounded-lg transition">
580
+ <span class="text-2xl">📚</span>
581
+ <div>
582
+ <div class="font-semibold">Forum</div>
583
+ <div class="text-sm text-mountain-400">In-depth discussions</div>
584
+ </div>
585
+ </a>
586
+ </div>
587
+ </div>
588
+ </div>
589
+
590
+ <!-- Still Stuck -->
591
+ <div class="bg-amber-900/30 border border-amber-600 rounded-xl p-6 mb-8">
592
+ <h2 class="text-xl font-bold mb-2 text-amber-400">🤔 Still Stuck?</h2>
593
+ <p class="text-mountain-300 mb-4">
594
+ If none of these solutions worked, try these steps in order:
595
+ </p>
596
+ <ol class="list-decimal list-inside text-mountain-300 space-y-2">
597
+ <li><strong>Restart your node</strong> - Sometimes a fresh start fixes things</li>
598
+ <li><strong>Update to latest version</strong> - <code class="bg-mountain-800 px-2 py-1 rounded">npm update -g yakmesh</code></li>
599
+ <li><strong>Check GitHub issues</strong> - Someone may have already solved your problem</li>
600
+ <li><strong>Ask in Discord</strong> - The community is usually quick to help</li>
601
+ <li><strong>Fresh install</strong> - As a last resort, backup keys and reinstall</li>
602
+ </ol>
603
+ </div>
604
+
605
+ <!-- Navigation Footer -->
606
+ <div class="border-t border-mountain-700 mt-12 pt-8">
607
+ <div class="flex flex-col sm:flex-row gap-4">
608
+ <a href="mobile-access.html" class="flex-1 block bg-mountain-800 border border-mountain-700 rounded-xl p-4 hover:border-emerald-500 transition group">
609
+ <div class="text-xs text-mountain-400 mb-1">← Previous</div>
610
+ <div class="flex items-center gap-2">
611
+ <span class="text-xl">📱</span>
612
+ <span class="font-semibold group-hover:text-emerald-400">Mobile Access</span>
613
+ </div>
614
+ </a>
615
+ <a href="../tutorials.html" class="flex-1 block bg-mountain-800 border border-mountain-700 rounded-xl p-4 hover:border-emerald-500 transition group">
616
+ <div class="text-xs text-mountain-400 mb-1">Back to</div>
617
+ <div class="flex items-center gap-2">
618
+ <span class="text-xl">📖</span>
619
+ <span class="font-semibold group-hover:text-emerald-400">All Tutorials</span>
620
+ </div>
621
+ </a>
622
+ </div>
623
+ </div>
624
+
625
+ </div>
626
+ </main>
627
+
628
+ <footer class="docs-footer">
629
+ <p>© 2026 YAKMESH™</p>
630
+ </footer>
631
+
632
+ <script src="../prism.min.js"></script>
633
+ <script src="../prism-bash.min.js"></script>
634
+ <script src="../prism-javascript.min.js"></script>
635
+ <script src="../docs.js"></script>
636
+ </body>
637
+ </html>