Initial commit

omni-ui: the Base upgrades, changelog, snapshots, and Vibenet demos site
(Next.js 15 App Router). Commit history squashed ahead of the public release.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: montycheese

.claude/commands/agents.md

@@ -0,0 +1,66 @@
+---
+description: Regenerate the public AGENTS.md routing document, or check whether it is stale
+---
+
+Manage the generated `public/AGENTS.md` — the **public** agent routing document
+served at `<origin>/AGENTS.md`.
+
+Argument: `$ARGUMENTS` — one of `check`, `status`, `force`, or empty.
+
+## Two different files
+
+Get this right before doing anything:
+
+- **`/AGENTS.md`** at the repo root is hand-written, follows the
+  [agents.md](https://agents.md/) spec, and describes how to work *in* this
+  repo. It is in no generator's `outputs`. Never regenerate it.
+- **`public/AGENTS.md`** is generated by `scripts/agents.mjs` and tells external
+  developers' agents how to use the site: routing rules, freshness, network
+  reference, route list.
+
+This command only concerns the second one.
+
+## Normally you do not need this
+
+`githooks/post-commit` runs it automatically when a commit message contains
+`agents.md`, and on any added, deleted, or renamed route file:
+
+```sh
+git commit -m "docs: refresh agents.md"
+```
+
+## What to do
+
+**No argument** — regenerate only if the route tree or config changed:
+
+```sh
+git diff --name-only HEAD -- src/app app llms.config.mjs
+node scripts/agents.mjs
+git diff --stat public/AGENTS.md
+```
+
+**`force`** — regenerate regardless.
+
+**`check`** — report staleness and validation failures without writing; exit 1
+if stale:
+
+```sh
+node scripts/agents.mjs --check
+```
+
+**`status`** — size, mtime, route count, config. Never fails.
+
+## When reviewing the diff
+
+Check these specifically, because they are the parts that would be damaging
+rather than merely wrong:
+
+- Each chain ID sits in the same `### ` block as its own RPC URL. A transposed
+  `8453` / `84532` reads perfectly fine and would have an agent signing against
+  the wrong network. There is a test for this; if it is failing, do not
+  work around it.
+- Ephemeral networks publish a note about where to read live values, not a
+  fabricated chain ID.
+- The routing rules still say which source wins on a conflict.
+
+To change content, edit `llms.config.mjs` — not the generated file.

.claude/commands/llms.md

@@ -0,0 +1,69 @@
+---
+description: Regenerate llms.txt and llms-full.txt, or check whether they are stale
+---
+
+Manage the generated `public/llms.txt` and `public/llms-full.txt`.
+
+Argument: `$ARGUMENTS` — one of `check`, `status`, `install`, or empty.
+
+## Normally you do not need this
+
+`githooks/post-commit` runs `scripts/llms.mjs` automatically when a commit
+message contains `llms.txt` (case-insensitive), and when a route file is added,
+deleted, or renamed. So the day-to-day flow is just:
+
+```sh
+git commit -m "feat: add a snapshots page; updates llms.txt"
+```
+
+Use `/llms` when you want to preview output before committing, regenerate
+without committing, or set the hook up on a fresh clone.
+
+## What to do
+
+**No argument** — regenerate and show what changed:
+
+```sh
+node scripts/llms.mjs
+git diff --stat public/llms.txt public/llms-full.txt
+```
+
+Report which files changed and summarise the diff. If nothing changed, say so
+plainly rather than implying work happened.
+
+**`check`** — report staleness without writing. Exit 1 means stale, invalid, or
+sitemap drift:
+
+```sh
+node scripts/llms.mjs --check
+```
+
+Relay the metadata-source breakdown. Any count under `metadata fallback` means
+those routes have no usable `export const metadata` and are being listed with a
+humanized slug — name them and suggest either adding metadata to the page or a
+`routes` override in `llms.config.mjs`.
+
+**`status`** — sizes, mtimes, config, route count, drift. Never fails:
+
+```sh
+node scripts/llms.mjs --status
+```
+
+**`install`** — set up the hook on this clone:
+
+```sh
+./githooks/install.sh
+```
+
+Then confirm it is repo-scoped: `git config --global --get core.hooksPath`
+should print nothing.
+
+## Do not
+
+- Edit `public/llms.txt` or the autogen region of `public/llms-full.txt` by
+  hand. Change the page's `export const metadata` or `llms.config.mjs` instead.
+- Touch the `<!-- LLMS_EXTRAS_START -->` … `<!-- LLMS_EXTRAS_END -->` region
+  unless the user asked for a prose change. That region is hand-written and
+  preserved verbatim across regenerations.
+- Confuse `public/AGENTS.md` (generated) with `/AGENTS.md` at the repo root
+  (hand-written, never generated).

.env.example

@@ -0,0 +1,38 @@
+# Vibenet dataplane API and RPC (public URLs, safe to expose to the client).
+NEXT_PUBLIC_VIBENET_API_BASE_URL=https://api.vibes.base.org
+NEXT_PUBLIC_VIBENET_RPC_URL=https://rpc.vibes.base.org
+
+# Snapshots: Cloudflare R2 credentials, read server-side by /api/snapshots.
+# These are secrets — set them in the Vercel project settings, not in git.
+# Provide per network (BASE_MAINNET_, BASE_SEPOLIA_, BASE_ZERONET_).
+# BASE_MAINNET_R2_ACCOUNT_ID=
+# BASE_MAINNET_R2_ACCESS_KEY_ID=
+# BASE_MAINNET_R2_SECRET_ACCESS_KEY=
+
+# Build/deploy target — selects which surfaces ship (see deploy.config.mjs).
+#   external (default) = public Vercel site; internal = Coinbase EKS (cb/ui),
+#   which includes internal-only sections like TIPS.
+#
+# Normally you don't set this by hand — the scripts do it:
+#   npm run dev            /  npm run build            -> external (default)
+#   npm run dev:internal   /  npm run build:internal   -> internal (TIPS visible)
+#
+# Set it here to change your local default (either value works), e.g. pin
+# `internal` so a plain `npm run dev` includes TIPS. The *:internal scripts still
+# win over this: a variable set in the shell by the npm script takes precedence
+# over .env.local, so you can always get either variant without editing this file.
+# Only affects local runs — Vercel sets no value, so the public build is external.
+# NEXT_PUBLIC_DEPLOY_TARGET=internal
+
+# TIPS: per-chain S3 + RPC, read server-side by /api/tips (chain via ?chain=).
+# One deployment serves all chains; provide a set per chain
+# (TIPS_MAINNET_, TIPS_SEPOLIA_, TIPS_ZERONET_). Secrets → Vercel env, not git.
+# TIPS_MAINNET_S3_BUCKET=
+# TIPS_MAINNET_S3_REGION=us-east-1
+# TIPS_MAINNET_S3_ENDPOINT=          # optional (e.g. MinIO); omit for AWS
+# TIPS_MAINNET_S3_ACCESS_KEY_ID=
+# TIPS_MAINNET_S3_SECRET_ACCESS_KEY=
+# TIPS_MAINNET_RPC_URL=
+# Per-chain block explorer for TIPS links (client-visible). Defaults:
+# mainnet=https://base.blockscout.com, sepolia=https://base-sepolia.blockscout.com.
+# NEXT_PUBLIC_TIPS_ZERONET_EXPLORER_URL=

.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "next/core-web-vitals"
+}

.github/workflows/ci.yml

@@ -0,0 +1,156 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+# Cancel superseded runs on the same PR/branch.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm test
+
+  # public/llms.txt, llms-full.txt, and AGENTS.md are generated from the route
+  # tree and committed. They go stale whenever a route is added, renamed, or
+  # removed, so this fails if they differ from a fresh generation (it also
+  # reports sitemap drift). Fix with: npm run llms && npm run agents
+  docs:
+    name: docs (generated agent index)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run docs:check
+
+  public-build-excludes-internal:
+    name: public build excludes internal-only surfaces
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+
+      # The default (external) build is what ships to Vercel. Deliberately no
+      # NEXT_PUBLIC_DEPLOY_TARGET here, so this reproduces the public build.
+      - run: npm run build
+
+      # Guards the deployment matrix in deploy.config.mjs: a surface that is not
+      # shipped to the external target must be unreachable on the public site.
+      # Without this, dropping the middleware rule — or adding an internal-only
+      # page and forgetting its SURFACES entry — would silently publish it.
+      - name: Assert internal-only surfaces are absent
+        run: |
+          set -euo pipefail
+
+          npx next start -p 3000 &
+          SERVER_PID=$!
+          trap 'kill $SERVER_PID 2>/dev/null || true' EXIT
+
+          for i in $(seq 1 60); do
+            if curl -fsS -o /dev/null http://localhost:3000/; then break; fi
+            if [ "$i" -eq 60 ]; then echo "server never became ready"; exit 1; fi
+            sleep 1
+          done
+
+          fail=0
+
+          # Internal-only routes must 404 on the public build.
+          for route in /tips /tips/block/0x1 /tips/bundles/0x1 /api/tips/blocks; do
+            code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:3000${route}")
+            if [ "${code}" != "404" ]; then
+              echo "FAIL: ${route} returned ${code}, expected 404"
+              fail=1
+            fi
+          done
+
+          # Pages that must stay public.
+          for route in / /snapshots; do
+            code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:3000${route}")
+            if [ "${code}" != "200" ]; then
+              echo "FAIL: ${route} returned ${code}, expected 200"
+              fail=1
+            fi
+          done
+
+          # No nav link to, or sitemap entry for, an internal-only section.
+          if curl -s http://localhost:3000/ | grep -q 'href="/tips"'; then
+            echo "FAIL: public homepage links to /tips"
+            fail=1
+          fi
+          if curl -s http://localhost:3000/sitemap.xml | grep -q '/tips'; then
+            echo "FAIL: public sitemap lists /tips"
+            fail=1
+          fi
+
+          if [ "${fail}" -ne 0 ]; then exit 1; fi
+          echo "OK: internal-only surfaces are absent from the public build"

.gitignore

@@ -0,0 +1,35 @@
+# dependencies
+/node_modules
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (keep .env.example)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+.claude/worktrees/
+.agents/skills/
+.claude/skills/
+skills-lock.json
+plans/

.npmrc

@@ -0,0 +1,5 @@
+# @vercel/analytics declares optional peers for other frameworks (e.g.
+# @sveltejs/kit) that npm's strict resolver conflicts against our vite/vitest
+# tree. We only use the Next.js path, so relax peer resolution for a clean,
+# reproducible install here and on Vercel's build.
+legacy-peer-deps=true

.nvmrc

@@ -0,0 +1 @@
+24