feat(docs): add MDX docs for voting, claims, treasury, and contract verification

Author: studiomonkeyx

.github/workflows/ci.yml

@@ -168,5 +168,6 @@ jobs:
 
       - run: npm ci
       - run: npm run lint
+      - run: npm run check-docs
       - run: npm run build
       - run: npm test

frontend/package.json

@@ -7,7 +7,8 @@
     "build": "next build",
     "analyze": "ANALYZE=true next build",
     "lint": "next lint",
-    "test": "jest --passWithNoTests"
+    "test": "jest --passWithNoTests",
+    "check-docs": "node scripts/check-docs-links.js"
   },
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
@@ -20,6 +21,7 @@
     "clsx": "^2.1.1",
     "lucide-react": "^1.7.0",
     "next": "15.2.3",
+    "next-mdx-remote": "^6.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-hook-form": "^7.72.0",

frontend/scripts/check-docs-links.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Checks that every internal link in src/content/*.mdx resolves to a known
+ * /docs/* route. Exits 1 if any broken links are found.
+ */
+const fs = require('fs')
+const path = require('path')
+
+const CONTENT_DIR = path.join(__dirname, '..', 'src', 'content')
+const VALID_ROUTES = new Set([
+  '/docs/voting',
+  '/docs/claims',
+  '/docs/treasury',
+  '/docs/contracts',
+])
+
+const LINK_RE = /\[([^\]]+)\]\(([^)]+)\)/g
+
+let broken = 0
+
+for (const file of fs.readdirSync(CONTENT_DIR).filter((f) => f.endsWith('.mdx'))) {
+  const src = fs.readFileSync(path.join(CONTENT_DIR, file), 'utf8')
+  for (const [, , href] of src.matchAll(LINK_RE)) {
+    if (!href.startsWith('/')) continue // skip external links
+    if (!VALID_ROUTES.has(href)) {
+      console.error(`[broken-link] ${file}: "${href}" is not a valid docs route`)
+      broken++
+    }
+  }
+}
+
+if (broken > 0) {
+  console.error(`\n${broken} broken internal link(s) found.`)
+  process.exit(1)
+} else {
+  console.log('All internal docs links OK.')
+}

frontend/src/app/docs/claims/page.tsx

@@ -0,0 +1,8 @@
+import { loadMdx } from '@/lib/load-mdx'
+
+export const metadata = { title: 'Claim Timelines — NiffyInsur Docs' }
+
+export default async function ClaimsPage() {
+  const { content } = await loadMdx('claims')
+  return <>{content}</>
+}

frontend/src/app/docs/contracts/page.tsx

@@ -0,0 +1,14 @@
+import { loadMdx } from '@/lib/load-mdx'
+import { ContractTable } from '@/components/docs/contract-table'
+
+export const metadata = { title: 'Contract Addresses — NiffyInsur Docs' }
+
+export default async function ContractsPage() {
+  const { content } = await loadMdx('contracts')
+  return (
+    <>
+      {content}
+      <ContractTable />
+    </>
+  )
+}

frontend/src/app/docs/layout.tsx

@@ -0,0 +1,30 @@
+import { DocsSidebar } from '@/components/docs/docs-sidebar'
+import Link from 'next/link'
+
+const GIT_SHA = process.env.NEXT_PUBLIC_GIT_SHA ?? process.env.VERCEL_GIT_COMMIT_SHA ?? ''
+
+export default function DocsLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen flex flex-col">
+      <header className="border-b bg-white px-6 py-3 flex items-center gap-4">
+        <Link href="/" className="text-sm font-semibold text-blue-600 hover:underline">
+          ← NiffyInsur
+        </Link>
+        <span className="text-gray-300">|</span>
+        <Link href="/docs/voting" className="text-sm font-medium text-gray-700">
+          Docs
+        </Link>
+      </header>
+
+      <div className="flex flex-1 max-w-5xl mx-auto w-full px-4 py-8 gap-8">
+        <DocsSidebar />
+        <main className="flex-1 min-w-0 prose prose-gray max-w-none">{children}</main>
+      </div>
+
+      <footer className="border-t px-6 py-3 text-xs text-gray-400 flex justify-between">
+        <span>NiffyInsur Docs</span>
+        {GIT_SHA && <span>Version: {GIT_SHA.slice(0, 7)}</span>}
+      </footer>
+    </div>
+  )
+}

frontend/src/app/docs/page.tsx

@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation'
+
+export default function DocsIndex() {
+  redirect('/docs/voting')
+}

frontend/src/app/docs/treasury/page.tsx

@@ -0,0 +1,8 @@
+import { loadMdx } from '@/lib/load-mdx'
+
+export const metadata = { title: 'Treasury & Pause — NiffyInsur Docs' }
+
+export default async function TreasuryPage() {
+  const { content } = await loadMdx('treasury')
+  return <>{content}</>
+}

frontend/src/app/docs/voting/page.tsx

@@ -0,0 +1,8 @@
+import { loadMdx } from '@/lib/load-mdx'
+
+export const metadata = { title: 'Voting Mechanics — NiffyInsur Docs' }
+
+export default async function VotingPage() {
+  const { content } = await loadMdx('voting')
+  return <>{content}</>
+}

frontend/src/components/docs/contract-table.tsx

@@ -0,0 +1,68 @@
+'use client'
+
+import { useState } from 'react'
+import { getContracts, type Network } from '@/lib/network-manifest'
+
+export function ContractTable() {
+  const [network, setNetwork] = useState<Network>('testnet')
+  const contracts = getContracts(network)
+
+  return (
+    <div className="my-6">
+      <div className="flex items-center gap-3 mb-4">
+        <span className="text-sm font-medium text-gray-700">Network:</span>
+        <div className="flex rounded-md border overflow-hidden text-sm">
+          {(['testnet', 'public'] as Network[]).map((n) => (
+            <button
+              key={n}
+              onClick={() => setNetwork(n)}
+              className={`px-3 py-1.5 transition-colors ${
+                network === n
+                  ? 'bg-blue-600 text-white'
+                  : 'bg-white text-gray-600 hover:bg-gray-50'
+              }`}
+            >
+              {n === 'public' ? 'Mainnet' : 'Testnet'}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <div className="overflow-x-auto rounded-lg border">
+        <table className="w-full text-sm">
+          <thead className="bg-gray-50 text-left">
+            <tr>
+              <th className="px-4 py-2 font-medium text-gray-600">Contract</th>
+              <th className="px-4 py-2 font-medium text-gray-600">Contract ID</th>
+              <th className="px-4 py-2 font-medium text-gray-600">WASM Hash</th>
+              <th className="px-4 py-2 font-medium text-gray-600">Deployed</th>
+              <th className="px-4 py-2 font-medium text-gray-600">Explorer</th>
+            </tr>
+          </thead>
+          <tbody>
+            {contracts.map((c) => (
+              <tr key={c.name} className="border-t">
+                <td className="px-4 py-2 font-mono font-medium">{c.name}</td>
+                <td className="px-4 py-2 font-mono text-xs break-all">{c.contractId}</td>
+                <td className="px-4 py-2 font-mono text-xs break-all">{c.expectedWasmHash}</td>
+                <td className="px-4 py-2 text-xs text-gray-500">
+                  {new Date(c.deployedAt).toLocaleDateString()}
+                </td>
+                <td className="px-4 py-2">
+                  <a
+                    href={c.stellarExpertUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="text-blue-600 hover:underline text-xs"
+                  >
+                    Stellar Expert ↗
+                  </a>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  )
+}