lightnode-sdk 0.7.20 → 0.8.1

package/README.md

@@ -484,11 +484,15 @@ npx lightnode add judge-web3                    # evaluator UI, wallet-signed
 npx lightnode add wagmi-setup                   # wallet wiring: lib/wagmi + providers + connect button
 ```
 
-The `*-web3` scaffolders and `wagmi-setup` write Next.js pages, so run them
-inside a Next.js app (`npx create-next-app@latest .` first if you have none).
+The `*-web3` scaffolders are one command end to end: run in an empty folder and
+they scaffold a Next.js app, write the page with a wired Connect button, bundle
+the wagmi config + providers + connect button, wrap your layout with
+`<Providers>`, and `npm install` the deps. Run inside an existing Next.js app
+and they skip the scaffold and just add what's missing. Opt out of the
+automation with `--no-scaffold` and `--no-install`.
 
 All `add` commands accept `--template auto|nextjs-api|hono|node`,
-`--net testnet|mainnet`, and `--force`.
+`--net testnet|mainnet`, `--force`, `--no-install`, and `--no-scaffold`.
 
 > If `add <name>` reports an unknown target, your `npx` cache is serving an
 > older CLI. Force the current release: `npx lightnode-sdk@latest add <name>`.

package/dist/add.d.ts

@@ -109,6 +109,30 @@ export declare function addWagmiSetup(opts?: AddOpts): {
     template: Template;
     network: Network;
 };
+export interface LayoutPatch {
+    path: string;
+    patched: boolean;
+    reason?: string;
+}
+/**
+ * Patch the project's root layout to import and wrap children in <Providers>.
+ * Returns what happened so the CLI can report it; never throws.
+ */
+export declare function patchLayoutWithProviders(cwd?: string): LayoutPatch;
+export declare const SCAFFOLD_GLOBALS_CSS = "@import \"tailwindcss\";\n\n/* dark mode via .dark class (we default the app to dark) */\n@custom-variant dark (&:is(.dark, .dark *));\n\n/* design tokens (light) - ported from lcai-chat-v2 */\n:root {\n  font-family: var(--font-inter), ui-sans-serif, system-ui, sans-serif;\n\n  --background: #ffffff;\n  --primary: #6767e9;\n  --primary-600: #5a4fd8;\n  --foreground: #09090b;\n  --card: #ffffff;\n  --card-foreground: #09090b;\n  --popover: #ffffff;\n  --popover-foreground: hsl(240 10% 3.9%);\n  --primary-foreground: #fafafa;\n  --secondary: hsl(240 4.8% 95.9%);\n  --secondary-foreground: hsl(240 5.9% 10%);\n  --muted: hsl(240 4.8% 95.9%);\n  --muted-foreground: hsl(240 3.8% 46.1%);\n  --accent: hsl(240 4.8% 95.9%);\n  --accent-foreground: hsl(240 5.9% 10%);\n  --destructive: #ef4d6a;\n  --destructive-foreground: hsl(0 0% 98%);\n  --success: #15bd77;\n  --warning: #eaa53d;\n  --border: hsl(240 5.9% 90%);\n  --input: hsl(240 5.9% 90%);\n  --ring: hsl(240 10% 3.9%);\n  --radius: 0.625rem;\n\n  --surface-base-subtle: rgba(34, 35, 42, 0.02);\n  --surface-base-faint: rgba(14, 18, 27, 0.04);\n  --surface-base-light: rgba(204, 206, 239, 0.16);\n  --surface-elevation-light: #ffffff;\n\n  --content-primary: #0f0f14;\n  --content-default: #373842;\n  --content-soft: #656678;\n  --content-extraLight: #9798b6;\n\n  --border-soft: rgba(14, 18, 27, 0.08);\n  --border-light: rgba(14, 18, 27, 0.06);\n}\n\n/* design tokens (dark) */\n.dark {\n  --background: #070710;\n  --foreground: hsl(0 0% 98%);\n  --card: #0f0f14;\n  --card-foreground: hsl(0 0% 98%);\n  --popover: #0f0f14;\n  --popover-foreground: hsl(0 0% 98%);\n  --primary: #7064e9;\n  --primary-600: #8c71f6;\n  --primary-foreground: hsl(0 0% 98%);\n  --secondary: hsl(240 3.7% 15.9%);\n  --secondary-foreground: hsl(0 0% 98%);\n  --muted: hsl(240 3.7% 15.9%);\n  --muted-foreground: hsl(240 5% 64.9%);\n  --accent: hsl(240 3.7% 15.9%);\n  --accent-foreground: hsl(0 0% 98%);\n  --destructive: #fb5a76;\n  --destructive-foreground: hsl(0 0% 98%);\n  --success: #22d68a;\n  --warning: #f5be5c;\n  --border: hsl(240 3.7% 15.9%);\n  --input: hsl(240 3.7% 15.9%);\n  --ring: hsl(240 4.9% 83.9%);\n\n  --surface-base-subtle: rgba(204, 206, 239, 0.02);\n  --surface-base-faint: rgba(204, 206, 239, 0.04);\n  --surface-base-light: rgba(204, 206, 239, 0.08);\n  --surface-elevation-light: #0f0f14;\n\n  --content-primary: #cccef0;\n  --content-default: #9798b6;\n  --content-soft: rgba(154, 156, 207, 0.8);\n  --content-extraLight: #9798b6;\n\n  --border-soft: rgba(204, 206, 239, 0.12);\n  --border-light: rgba(204, 206, 239, 0.08);\n}\n\n/* theme mapping (Tailwind v4 @theme) */\n@theme inline {\n  --radius-md: calc(var(--radius) - 2px);\n  --radius-sm: calc(var(--radius) - 4px);\n  --radius-lg: var(--radius);\n\n  --color-background: var(--background);\n  --color-foreground: var(--foreground);\n  --color-card: var(--card);\n  --color-card-foreground: var(--card-foreground);\n  --color-popover: var(--popover);\n  --color-popover-foreground: var(--popover-foreground);\n  --color-primary: var(--primary);\n  --color-primary-600: var(--primary-600);\n  --color-primary-foreground: var(--primary-foreground);\n  --color-secondary: var(--secondary);\n  --color-secondary-foreground: var(--secondary-foreground);\n  --color-muted: var(--muted);\n  --color-muted-foreground: var(--muted-foreground);\n  --color-accent: var(--accent);\n  --color-accent-foreground: var(--accent-foreground);\n  --color-destructive: var(--destructive);\n  --color-destructive-foreground: var(--destructive-foreground);\n  --color-success: var(--success);\n  --color-warning: var(--warning);\n  --color-border: var(--border);\n  --color-input: var(--input);\n  --color-ring: var(--ring);\n\n  --color-surface-base-subtle: var(--surface-base-subtle);\n  --color-surface-base-faint: var(--surface-base-faint);\n  --color-surface-base-light: var(--surface-base-light);\n  --color-surface-elevation-light: var(--surface-elevation-light);\n  --color-surface-base-brand-default: #693ee0;\n  --color-surface-base-brand-strong: #8c71f6;\n\n  --color-content-primary: var(--content-primary);\n  --color-content-default: var(--content-default);\n  --color-content-soft: var(--content-soft);\n  --color-content-extraLight: var(--content-extraLight);\n\n  --color-bdr-soft: var(--border-soft);\n  --color-bdr-light: var(--border-light);\n\n  --color-gradient-primary: linear-gradient(270deg, #7064e9 0%, #dd00ac 100%);\n}\n\n@layer base {\n  * {\n    border-color: var(--border);\n  }\n  body {\n    background-color: var(--background);\n    color: var(--foreground);\n    overflow-x: hidden;\n  }\n  html {\n    overflow-x: hidden;\n  }\n  button {\n    cursor: pointer;\n  }\n  button:disabled {\n    cursor: not-allowed;\n  }\n  /* visible keyboard focus across interactive elements */\n  a:focus-visible,\n  button:focus-visible,\n  input:focus-visible,\n  select:focus-visible,\n  textarea:focus-visible {\n    outline: 2px solid var(--primary);\n    outline-offset: 2px;\n    border-radius: 6px;\n  }\n}\n\n/* respect reduced-motion: kill non-essential animation */\n@media (prefers-reduced-motion: reduce) {\n  *,\n  ::before,\n  ::after {\n    animation-duration: 0.001ms !important;\n    animation-iteration-count: 1 !important;\n    transition-duration: 0.001ms !important;\n    scroll-behavior: auto !important;\n  }\n}\n\n/* ambient app background (gradient mesh behind everything) */\nbody::before {\n  content: \"\";\n  position: fixed;\n  inset: 0;\n  z-index: -1;\n  pointer-events: none;\n  background:\n    radial-gradient(60% 50% at 50% -6%, rgba(221, 0, 172, 0.10), transparent 60%),\n    radial-gradient(55% 45% at 12% -8%, rgba(112, 100, 233, 0.14), transparent 60%),\n    radial-gradient(50% 40% at 88% -2%, rgba(112, 100, 233, 0.12), transparent 60%),\n    radial-gradient(45% 45% at 50% 115%, rgba(112, 100, 233, 0.07), transparent 60%);\n}\n.dark body::before {\n  background:\n    radial-gradient(60% 50% at 50% -6%, rgba(221, 0, 172, 0.12), transparent 60%),\n    radial-gradient(55% 45% at 12% -8%, rgba(112, 100, 233, 0.18), transparent 60%),\n    radial-gradient(50% 40% at 88% -2%, rgba(112, 100, 233, 0.14), transparent 60%),\n    radial-gradient(45% 45% at 50% 118%, rgba(112, 100, 233, 0.10), transparent 60%);\n}\n\n/* minimal scrollbar */\n::-webkit-scrollbar {\n  width: 6px;\n  height: 6px;\n}\n::-webkit-scrollbar-track {\n  background: transparent;\n}\n::-webkit-scrollbar-thumb {\n  background: var(--border);\n  border-radius: 3px;\n}\n* {\n  scrollbar-width: thin;\n  scrollbar-color: var(--border) transparent;\n}\n";
+export interface ScaffoldWiring {
+    written: WrittenFile[];
+    /** The route now also served at `/` (e.g. "/chat-web3"), or null if nothing was wired. */
+    homepageRoute: string | null;
+    /** Whether the `dark` class was added to <html> (dark kept as the default). */
+    darkDefault: boolean;
+}
+/**
+ * Wire a freshly scaffolded Next.js app so the generated -web3 page is the
+ * homepage and the LightChain theme + dark default are in place. No-op for any
+ * target without a known route folder.
+ */
+export declare function wireFreshScaffold(target: string, opts?: AddOpts): ScaffoldWiring;
 export declare function addJudge(opts?: AddOpts): {
     written: WrittenFile[];
     install: string;

package/dist/add.js

@@ -964,6 +964,7 @@ const NEXTJS_CHAT_WEB3_PAGE = `// app/chat-web3/page.tsx
 import { useEffect, useState } from "react";
 import { useAccount, useWalletClient, usePublicClient } from "wagmi";
 import { siweSignIn, GatewayClient, runInference, estimateJobFee, NETWORKS } from "lightnode-sdk";
+import { ConnectButton } from "@/components/connect-button";
 
 type Turn = {
   role: "user" | "assistant";
@@ -1074,16 +1075,19 @@ export default function ChatWeb3() {
 
   return (
     <main style={{ maxWidth: 720, margin: "32px auto", padding: 16, fontFamily: "system-ui" }}>
-      <h1>Chat (user-pays)</h1>
+      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12 }}>
+        <h1>Chat (user-pays)</h1>
+        <ConnectButton />
+      </div>
       <p style={{ color: "#666" }}>
         Each turn signs one createSession transaction from your wallet on{" "}
         <code>{network ?? "(connect a wallet)"}</code>. Fee:{" "}
         <code>{feeLcai != null ? \`\${feeLcai} LCAI\` : "(fetching)"}</code> per turn plus a small gas amount.
       </p>
       {!address && (
-        <div style={{ border: "1px solid #ddd", borderRadius: 8, padding: 12, margin: "12px 0" }}>
-          Connect a wallet to start chatting. (Use whichever connector your app exposes - e.g. RainbowKit,
-          ConnectKit, Reown AppKit, or wagmi&apos;s useConnect directly.)
+        <div style={{ border: "1px solid #ddd", borderRadius: 8, padding: 12, margin: "12px 0", display: "flex", alignItems: "center", gap: 12 }}>
+          <span>Connect a wallet to start chatting.</span>
+          <ConnectButton />
         </div>
       )}
 
@@ -1166,6 +1170,7 @@ const NEXTJS_INFERENCE_WEB3_PAGE = `// app/inference-web3/page.tsx
 import { useEffect, useState } from "react";
 import { useAccount, useWalletClient, usePublicClient } from "wagmi";
 import { siweSignIn, GatewayClient, runInference, estimateJobFee, NETWORKS } from "lightnode-sdk";
+import { ConnectButton } from "@/components/connect-button";
 
 type Result = {
   answer: string;
@@ -1254,15 +1259,19 @@ export default function InferenceWeb3() {
 
   return (
     <main style={{ maxWidth: 720, margin: "32px auto", padding: 16, fontFamily: "system-ui" }}>
-      <h1>Inference (user-pays)</h1>
+      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12 }}>
+        <h1>Inference (user-pays)</h1>
+        <ConnectButton />
+      </div>
       <p style={{ color: "#666" }}>
         Signs one encrypted inference from your wallet on{" "}
         <code>{network ?? "(connect a wallet)"}</code>. Fee:{" "}
         <code>{feeLcai != null ? \`\${feeLcai} LCAI\` : "(fetching)"}</code> per call plus a small gas amount.
       </p>
       {!address && (
-        <div style={{ border: "1px solid #ddd", borderRadius: 8, padding: 12, margin: "12px 0" }}>
-          Connect a wallet to run inference. Drop &lt;ConnectButton /&gt; here or wherever your app exposes one.
+        <div style={{ border: "1px solid #ddd", borderRadius: 8, padding: 12, margin: "12px 0", display: "flex", alignItems: "center", gap: 12 }}>
+          <span>Connect a wallet to run inference.</span>
+          <ConnectButton />
         </div>
       )}
 
@@ -1321,6 +1330,7 @@ const NEXTJS_JUDGE_WEB3_PAGE = `// app/judge-web3/page.tsx
 import { useEffect, useState } from "react";
 import { useAccount, useWalletClient, usePublicClient } from "wagmi";
 import { siweSignIn, GatewayClient, runInference, estimateJobFee, NETWORKS } from "lightnode-sdk";
+import { ConnectButton } from "@/components/connect-button";
 
 type Verdict = {
   passed: boolean;
@@ -1434,15 +1444,19 @@ Reply with STRICT JSON only, matching: { "passed": boolean, "confidence": 0-1, "
 
   return (
     <main style={{ maxWidth: 720, margin: "32px auto", padding: 16, fontFamily: "system-ui" }}>
-      <h1>AI Judge (user-pays)</h1>
+      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12 }}>
+        <h1>AI Judge (user-pays)</h1>
+        <ConnectButton />
+      </div>
       <p style={{ color: "#666" }}>
         Each submission signs one inference from your wallet on{" "}
         <code>{network ?? "(connect a wallet)"}</code>. Cost:{" "}
         <code>{feeLcai != null ? \`\${feeLcai} LCAI\` : "(fetching)"}</code> plus gas. Verdict comes back with on-chain proof.
       </p>
       {!address && (
-        <div style={{ border: "1px solid #ddd", borderRadius: 8, padding: 12, margin: "12px 0" }}>
-          Connect a wallet to submit. Drop &lt;ConnectButton /&gt; here or wherever your app exposes one.
+        <div style={{ border: "1px solid #ddd", borderRadius: 8, padding: 12, margin: "12px 0", display: "flex", alignItems: "center", gap: 12 }}>
+          <span>Connect a wallet to submit.</span>
+          <ConnectButton />
         </div>
       )}
 
@@ -1983,6 +1997,372 @@ export function addWagmiSetup(opts = {}) {
         network,
     };
 }
+function findLayoutFile(cwd) {
+    const candidates = ["app/layout.tsx", "app/layout.jsx", "src/app/layout.tsx", "src/app/layout.jsx"];
+    for (const rel of candidates) {
+        const abs = path.join(cwd, rel);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+function withProvidersImport(source) {
+    if (/from\s+["']\.\/providers["']/.test(source))
+        return source;
+    const importLine = `import { Providers } from "./providers";`;
+    const lines = source.split("\n");
+    let lastImport = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*import\s/.test(lines[i]))
+            lastImport = i;
+    }
+    if (lastImport === -1)
+        return `${importLine}\n${source}`;
+    return [...lines.slice(0, lastImport + 1), importLine, ...lines.slice(lastImport + 1)].join("\n");
+}
+function withWrappedChildren(source) {
+    if (/<Providers>/.test(source))
+        return source;
+    if (!source.includes("{children}"))
+        return null;
+    return source.replace("{children}", "<Providers>{children}</Providers>");
+}
+/**
+ * Patch the project's root layout to import and wrap children in <Providers>.
+ * Returns what happened so the CLI can report it; never throws.
+ */
+export function patchLayoutWithProviders(cwd = process.cwd()) {
+    const abs = findLayoutFile(cwd);
+    if (!abs)
+        return { path: "app/layout.tsx", patched: false, reason: "no layout file found" };
+    const rel = path.relative(cwd, abs) || abs;
+    let source;
+    try {
+        source = fs.readFileSync(abs, "utf8");
+    }
+    catch (e) {
+        return { path: rel, patched: false, reason: `could not read layout (${e.message})` };
+    }
+    if (/<Providers>/.test(source) && /from\s+["']\.\/providers["']/.test(source)) {
+        return { path: rel, patched: false, reason: "already wrapped with <Providers>" };
+    }
+    const wrapped = withWrappedChildren(withProvidersImport(source));
+    if (wrapped === null) {
+        return { path: rel, patched: false, reason: "no {children} found - wrap with <Providers> manually" };
+    }
+    try {
+        fs.writeFileSync(abs, wrapped);
+    }
+    catch (e) {
+        return { path: rel, patched: false, reason: `could not write layout (${e.message})` };
+    }
+    return { path: rel, patched: true };
+}
+// ---------------------------------------------------------------------------
+// Fresh-scaffold wiring: when `add <x>-web3` scaffolds a brand-new Next.js app
+// (bare folder), the create-next-app starter page sits at `/` and the generated
+// page sits at `/<x>-web3`, so `npm run dev` + localhost:3000 lands on the
+// starter, not the chat. This makes the generated page the homepage and ships
+// the LightChain theme so the first render is the real thing.
+//
+// Only ever invoked on a scaffold WE just created, so overwriting page.tsx and
+// globals.css is safe - there is no user content to clobber. In an existing app
+// none of this runs; the page keeps its dedicated /<x>-web3 route untouched.
+// ---------------------------------------------------------------------------
+// The LightChain chat theme (Tailwind v4 tokens, light + dark), ported from the
+// lightnode app's globals.css. Shipped as the scaffold's app/globals.css so
+// installs default to the real look instead of the create-next-app starter.
+export const SCAFFOLD_GLOBALS_CSS = `@import "tailwindcss";
+
+/* dark mode via .dark class (we default the app to dark) */
+@custom-variant dark (&:is(.dark, .dark *));
+
+/* design tokens (light) - ported from lcai-chat-v2 */
+:root {
+  font-family: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
+
+  --background: #ffffff;
+  --primary: #6767e9;
+  --primary-600: #5a4fd8;
+  --foreground: #09090b;
+  --card: #ffffff;
+  --card-foreground: #09090b;
+  --popover: #ffffff;
+  --popover-foreground: hsl(240 10% 3.9%);
+  --primary-foreground: #fafafa;
+  --secondary: hsl(240 4.8% 95.9%);
+  --secondary-foreground: hsl(240 5.9% 10%);
+  --muted: hsl(240 4.8% 95.9%);
+  --muted-foreground: hsl(240 3.8% 46.1%);
+  --accent: hsl(240 4.8% 95.9%);
+  --accent-foreground: hsl(240 5.9% 10%);
+  --destructive: #ef4d6a;
+  --destructive-foreground: hsl(0 0% 98%);
+  --success: #15bd77;
+  --warning: #eaa53d;
+  --border: hsl(240 5.9% 90%);
+  --input: hsl(240 5.9% 90%);
+  --ring: hsl(240 10% 3.9%);
+  --radius: 0.625rem;
+
+  --surface-base-subtle: rgba(34, 35, 42, 0.02);
+  --surface-base-faint: rgba(14, 18, 27, 0.04);
+  --surface-base-light: rgba(204, 206, 239, 0.16);
+  --surface-elevation-light: #ffffff;
+
+  --content-primary: #0f0f14;
+  --content-default: #373842;
+  --content-soft: #656678;
+  --content-extraLight: #9798b6;
+
+  --border-soft: rgba(14, 18, 27, 0.08);
+  --border-light: rgba(14, 18, 27, 0.06);
+}
+
+/* design tokens (dark) */
+.dark {
+  --background: #070710;
+  --foreground: hsl(0 0% 98%);
+  --card: #0f0f14;
+  --card-foreground: hsl(0 0% 98%);
+  --popover: #0f0f14;
+  --popover-foreground: hsl(0 0% 98%);
+  --primary: #7064e9;
+  --primary-600: #8c71f6;
+  --primary-foreground: hsl(0 0% 98%);
+  --secondary: hsl(240 3.7% 15.9%);
+  --secondary-foreground: hsl(0 0% 98%);
+  --muted: hsl(240 3.7% 15.9%);
+  --muted-foreground: hsl(240 5% 64.9%);
+  --accent: hsl(240 3.7% 15.9%);
+  --accent-foreground: hsl(0 0% 98%);
+  --destructive: #fb5a76;
+  --destructive-foreground: hsl(0 0% 98%);
+  --success: #22d68a;
+  --warning: #f5be5c;
+  --border: hsl(240 3.7% 15.9%);
+  --input: hsl(240 3.7% 15.9%);
+  --ring: hsl(240 4.9% 83.9%);
+
+  --surface-base-subtle: rgba(204, 206, 239, 0.02);
+  --surface-base-faint: rgba(204, 206, 239, 0.04);
+  --surface-base-light: rgba(204, 206, 239, 0.08);
+  --surface-elevation-light: #0f0f14;
+
+  --content-primary: #cccef0;
+  --content-default: #9798b6;
+  --content-soft: rgba(154, 156, 207, 0.8);
+  --content-extraLight: #9798b6;
+
+  --border-soft: rgba(204, 206, 239, 0.12);
+  --border-light: rgba(204, 206, 239, 0.08);
+}
+
+/* theme mapping (Tailwind v4 @theme) */
+@theme inline {
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-lg: var(--radius);
+
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-600: var(--primary-600);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --color-surface-base-subtle: var(--surface-base-subtle);
+  --color-surface-base-faint: var(--surface-base-faint);
+  --color-surface-base-light: var(--surface-base-light);
+  --color-surface-elevation-light: var(--surface-elevation-light);
+  --color-surface-base-brand-default: #693ee0;
+  --color-surface-base-brand-strong: #8c71f6;
+
+  --color-content-primary: var(--content-primary);
+  --color-content-default: var(--content-default);
+  --color-content-soft: var(--content-soft);
+  --color-content-extraLight: var(--content-extraLight);
+
+  --color-bdr-soft: var(--border-soft);
+  --color-bdr-light: var(--border-light);
+
+  --color-gradient-primary: linear-gradient(270deg, #7064e9 0%, #dd00ac 100%);
+}
+
+@layer base {
+  * {
+    border-color: var(--border);
+  }
+  body {
+    background-color: var(--background);
+    color: var(--foreground);
+    overflow-x: hidden;
+  }
+  html {
+    overflow-x: hidden;
+  }
+  button {
+    cursor: pointer;
+  }
+  button:disabled {
+    cursor: not-allowed;
+  }
+  /* visible keyboard focus across interactive elements */
+  a:focus-visible,
+  button:focus-visible,
+  input:focus-visible,
+  select:focus-visible,
+  textarea:focus-visible {
+    outline: 2px solid var(--primary);
+    outline-offset: 2px;
+    border-radius: 6px;
+  }
+}
+
+/* respect reduced-motion: kill non-essential animation */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  ::before,
+  ::after {
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.001ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* ambient app background (gradient mesh behind everything) */
+body::before {
+  content: "";
+  position: fixed;
+  inset: 0;
+  z-index: -1;
+  pointer-events: none;
+  background:
+    radial-gradient(60% 50% at 50% -6%, rgba(221, 0, 172, 0.10), transparent 60%),
+    radial-gradient(55% 45% at 12% -8%, rgba(112, 100, 233, 0.14), transparent 60%),
+    radial-gradient(50% 40% at 88% -2%, rgba(112, 100, 233, 0.12), transparent 60%),
+    radial-gradient(45% 45% at 50% 115%, rgba(112, 100, 233, 0.07), transparent 60%);
+}
+.dark body::before {
+  background:
+    radial-gradient(60% 50% at 50% -6%, rgba(221, 0, 172, 0.12), transparent 60%),
+    radial-gradient(55% 45% at 12% -8%, rgba(112, 100, 233, 0.18), transparent 60%),
+    radial-gradient(50% 40% at 88% -2%, rgba(112, 100, 233, 0.14), transparent 60%),
+    radial-gradient(45% 45% at 50% 118%, rgba(112, 100, 233, 0.10), transparent 60%);
+}
+
+/* minimal scrollbar */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background: var(--border);
+  border-radius: 3px;
+}
+* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--border) transparent;
+}
+`;
+/** Map an `add` target to the route folder its page lives in. */
+const WEB3_ROUTE_DIR = {
+    "chat-web3": "chat-web3",
+    "inference-web3": "inference-web3",
+    "judge-web3": "judge-web3",
+};
+/** The app/page.tsx we drop in to make the generated page the homepage. It
+ *  re-exports the real page so its documented /<target> route still works. */
+function homepageReexport(dir, target) {
+    return `// app/page.tsx
+// Generated by 'lightnode add ${target}'. Makes the ${dir} page the homepage so
+// 'npm run dev' + http://localhost:3000 lands on it directly. The page itself
+// still lives at app/${dir}/page.tsx and is also served at /${dir}.
+export { default } from "./${dir}/page";
+`;
+}
+/** Add the \`dark\` class to the layout's <html> element so dark stays the
+ *  default theme. Returns the patched source, or null if <html> was not found
+ *  or already carries a \`dark\` class. Handles className as a template literal,
+ *  a string literal, or absent. */
+function withDarkHtml(source) {
+    const match = source.match(/<html\b[^>]*>/);
+    if (!match)
+        return null;
+    const tag = match[0];
+    // Already dark? Cover both className={`...dark...`} and className="...dark...".
+    if (/className=\{`[^`]*\bdark\b/.test(tag) || /className=(["'])[^"']*\bdark\b/.test(tag))
+        return null;
+    if (/className=\{`/.test(tag)) {
+        return source.replace(tag, tag.replace(/className=\{`/, "className={`dark "));
+    }
+    if (/className=(["'])/.test(tag)) {
+        return source.replace(tag, tag.replace(/className=(["'])/, 'className=$1dark '));
+    }
+    // No className on <html>: add one.
+    return source.replace(tag, tag.replace(/<html\b/, '<html className="dark"'));
+}
+function setDarkDefaultOnLayout(cwd) {
+    const abs = findLayoutFile(cwd);
+    if (!abs)
+        return false;
+    let source;
+    try {
+        source = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const patched = withDarkHtml(source);
+    if (patched === null)
+        return false;
+    try {
+        fs.writeFileSync(abs, patched);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/**
+ * Wire a freshly scaffolded Next.js app so the generated -web3 page is the
+ * homepage and the LightChain theme + dark default are in place. No-op for any
+ * target without a known route folder.
+ */
+export function wireFreshScaffold(target, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const dir = WEB3_ROUTE_DIR[target];
+    const written = [];
+    if (!dir)
+        return { written, homepageRoute: null, darkDefault: false };
+    // 1. Ship the LightChain theme, replacing the create-next-app starter globals.
+    written.push(writeFile(path.join(cwd, "app/globals.css"), SCAFFOLD_GLOBALS_CSS, true));
+    // 2. Make the generated page the homepage (replaces the starter page.tsx).
+    written.push(writeFile(path.join(cwd, "app/page.tsx"), homepageReexport(dir, target), true));
+    // 3. Keep dark as the default theme (matches lightnode.app).
+    const darkDefault = setDarkDefaultOnLayout(cwd);
+    return { written, homepageRoute: `/${dir}`, darkDefault };
+}
 const NEXTJS_JUDGE_ROUTE = `// app/api/judge/route.ts
 // Generated by 'lightnode add judge'. See https://lightnode.app/build
 // The LightChallenge-style evaluator: post evidence + criteria, get a

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, runInferenceBatch, Agent, isStalledWorker, workerPreflight, workerWatch, WorkerOperator, isWorkerOpError, BRIDGE_ROUTE, DAO, DAO_ADDRESSES, SDK_VERSION } from "./index.js";
-import { addInference, addInferenceWeb3, addJudgeWeb3, addAnalyticsDashboard, addNftMint, addChat, addChatWeb3, addAgent, addJudge, addWagmiSetup } from "./add.js";
+import { addInference, addInferenceWeb3, addJudgeWeb3, addAnalyticsDashboard, addNftMint, addChat, addChatWeb3, addAgent, addJudge, addWagmiSetup, patchLayoutWithProviders, wireFreshScaffold } from "./add.js";
 import { createPublicClient, createWalletClient, http, parseEther } from "viem";
 import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { spawnSync } from "node:child_process";
 function flag(name) {
     const i = process.argv.indexOf(name);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -19,6 +20,71 @@ function die(msg) {
 }
 const lcai = (wei) => (wei ? Number(BigInt(wei)) / 1e18 : 0);
 const rate = (r) => (r == null ? "-" : `${Math.round(r * 100)}%`);
+// `add` targets that are always a Next.js client page. In a bare folder these
+// get a real Next.js app scaffolded first so the generated page can render.
+const NEXT_PAGE_TARGETS = new Set(["chat-web3", "inference-web3", "judge-web3", "wagmi-setup"]);
+function printWritten(files) {
+    for (const f of files) {
+        if (f.skipped)
+            console.log(`  ⤴ ${f.path} (skipped - ${f.reason})`);
+        else
+            console.log(`  ✓ ${f.path}`);
+    }
+}
+/**
+ * Scaffold a Next.js app into cwd via create-next-app. Returns true on success.
+ *
+ * We scaffold into a fixed-name subfolder and move the files up rather than
+ * passing ".", because create-next-app derives the project name from the
+ * target and rejects names npm won't allow (capital letters, leading dots,
+ * etc.) - which would make this fail in any folder like "MyApp". The subfolder
+ * name is one we control, so that validation always passes.
+ */
+function scaffoldNextApp(cwd, target) {
+    console.log(`\nNo Next.js app here yet - scaffolding one with create-next-app...\n`);
+    const stageName = "lightnode-next-app-stage";
+    const args = [
+        "--yes", "create-next-app@latest", stageName,
+        "--ts", "--app", "--no-src-dir", "--eslint", "--tailwind",
+        "--use-npm", "--no-turbopack", "--import-alias", "@/*",
+    ];
+    const r = spawnSync("npx", args, { cwd, stdio: "inherit" });
+    if (r.status !== 0) {
+        console.error(`\ncreate-next-app did not complete (exit ${r.status ?? "?"}).`);
+        console.error(`If this folder already had files, scaffold manually then re-run:`);
+        console.error(`  npx create-next-app@latest .  &&  npx lightnode-sdk@latest add ${target}`);
+        return false;
+    }
+    return relocateScaffold(join(cwd, stageName), cwd, target);
+}
+/** Move every entry from the staged scaffold dir up into cwd, then remove it. */
+function relocateScaffold(from, cwd, target) {
+    try {
+        for (const entry of readdirSync(from)) {
+            const dest = join(cwd, entry);
+            if (existsSync(dest))
+                continue; // never clobber files the user already had
+            renameSync(join(from, entry), dest);
+        }
+        rmSync(from, { recursive: true, force: true });
+        return true;
+    }
+    catch (e) {
+        console.error(`\nScaffolded into ${from} but could not move it up (${e.message}).`);
+        console.error(`Move its contents into this folder, then re-run: npx lightnode-sdk@latest add ${target}`);
+        return false;
+    }
+}
+/** Run an `npm install ...` line in cwd. The line is an internal constant
+ *  (never user input), so running it through a shell is safe here. */
+function installDeps(installLine, cwd) {
+    console.log(`\nInstalling dependencies: ${installLine}\n`);
+    const r = spawnSync(installLine, { cwd, stdio: "inherit", shell: true });
+    if (r.status === 0)
+        return true;
+    console.error(`\nDependency install failed (exit ${r.status ?? "?"}). Run it yourself:\n  ${installLine}`);
+    return false;
+}
 const HELP = `lightnode <command> [--net mainnet|testnet]
 
 Run one inference (needs PRIVATE_KEY in env):
@@ -505,6 +571,18 @@ async function main() {
                 }
                 die(lines.join("\n"));
             }
+            // ---- one-command setup: flags + optional scaffold ----
+            const noInstall = process.argv.includes("--no-install");
+            const noScaffold = process.argv.includes("--no-scaffold");
+            const cwd = process.cwd();
+            const isWeb3Page = sub === "chat-web3" || sub === "inference-web3" || sub === "judge-web3";
+            // A Next.js client page needs a Next.js app to live in. In a bare folder,
+            // scaffold one first so the generated page renders instead of throwing
+            // "Cannot find module 'react'". Opt out with --no-scaffold.
+            const didScaffold = NEXT_PAGE_TARGETS.has(sub ?? "") && !existsSync(join(cwd, "package.json")) && !noScaffold
+                ? scaffoldNextApp(cwd, sub ?? "")
+                : false;
+            // ---- write the requested files ----
             const result = sub === "analytics-dashboard" ? addAnalyticsDashboard({ template, network, force })
                 : sub === "nft-mint-with-inference" ? addNftMint({ template, network, force })
                     : sub === "chat-web3" ? addChatWeb3({ template, network, force })
@@ -516,71 +594,68 @@ async function main() {
                                             : sub === "judge" ? addJudge({ template, network, force })
                                                 : addInference({ template, network, force });
             console.log(`▶ add ${sub} (${result.template} template, default network ${result.network})`);
-            for (const f of result.written) {
-                if (f.skipped)
-                    console.log(`  ⤴ ${f.path} (skipped - ${f.reason})`);
+            printWritten(result.written);
+            // ---- web3 pages: bundle the wagmi wiring + wrap the root layout so the
+            // page's <ConnectButton /> and wagmi hooks have a provider to resolve. ----
+            let layout = null;
+            if (isWeb3Page) {
+                const wagmi = addWagmiSetup({ template: result.template, network, force });
+                printWritten(wagmi.written);
+            }
+            if (isWeb3Page || sub === "wagmi-setup") {
+                layout = patchLayoutWithProviders(cwd);
+                if (layout.patched)
+                    console.log(`  ✓ ${layout.path} (wrapped children with <Providers>)`);
                 else
-                    console.log(`  ✓ ${f.path}`);
-            }
-            const anyWritten = result.written.some((f) => !f.skipped);
-            if (!anyWritten) {
-                console.log("\nNothing to do - all target files already exist. Pass --force to overwrite.");
-            }
-            else {
-                // The *-web3 pages and wagmi-setup are Next.js React files. If no
-                // Next.js app was detected (e.g. an empty folder), nothing can render
-                // what we just wrote - surface that before the numbered steps so the
-                // user scaffolds an app first instead of chasing a non-running page.
-                const isNextOnly = sub === "chat-web3" || sub === "inference-web3" || sub === "judge-web3" || sub === "wagmi-setup";
-                const hasPackageJson = existsSync(join(process.cwd(), "package.json"));
-                if (isNextOnly && result.template !== "nextjs-api") {
-                    console.log(`\nNo Next.js app detected in this folder. ${sub} is a Next.js page, so`);
-                    console.log(`create one here first, then re-run this command:`);
-                    console.log(`  npx create-next-app@latest .`);
-                }
-                else if (!hasPackageJson) {
-                    // A scaffolded script dropped into a bare folder (no package.json)
-                    // gives the editor nothing to resolve Node/ws types against - the
-                    // user sees "Cannot find name 'process'" everywhere. Initialize a
-                    // project first so the install below lands in a real node_modules.
-                    console.log(`\nNo package.json in this folder yet, so your editor can't resolve types`);
-                    console.log(`(you'd see "Cannot find name 'process'" etc.). Initialize a project first:`);
-                    console.log(`  npm init -y`);
-                }
-                console.log(`\nNext steps (these files were added to your CURRENT folder, not a new project):`);
-                console.log(`  1. ${result.install}`);
-                if (sub === "wagmi-setup") {
-                    console.log(`  2. Import Providers in app/layout.tsx and wrap children:`);
-                    console.log(`     import { Providers } from "./providers";`);
-                    console.log(`     // <body><Providers>{children}</Providers></body>`);
-                    console.log(`  3. Drop <ConnectButton /> anywhere you want a connect UI:`);
-                    console.log(`     import { ConnectButton } from "@/components/connect-button";`);
-                    console.log(`  4. You can now use any wagmi hook (useAccount, useWalletClient, ...).`);
-                    console.log(`     Wallets on chains other than 9200/8200 will be prompted to switch.`);
+                    console.log(`  ⤴ ${layout.path} (${layout.reason})`);
+            }
+            // ---- fresh scaffold only: make the generated page the homepage and ship
+            // the LightChain theme so localhost:3000 lands on the chat, not the
+            // create-next-app starter. Skipped in an existing app (nothing to clobber).
+            let wiring = null;
+            if (didScaffold && isWeb3Page) {
+                wiring = wireFreshScaffold(sub, { cwd });
+                printWritten(wiring.written);
+                if (wiring.homepageRoute)
+                    console.log(`  ✓ app/page.tsx (chat is now the homepage at /)`);
+                if (wiring.darkDefault)
+                    console.log(`  ✓ app/layout.tsx (dark theme default)`);
+            }
+            // ---- install dependencies (opt out with --no-install) ----
+            const installed = noInstall ? false : installDeps(result.install, cwd);
+            // ---- next steps ----
+            const layoutNeedsManual = layout != null && !layout.patched && !/already/.test(layout.reason ?? "");
+            if (isWeb3Page) {
+                const route = sub === "chat-web3" ? "/chat-web3" : sub === "inference-web3" ? "/inference-web3" : "/judge-web3";
+                const chainId = result.network === "mainnet" ? "9200" : "8200";
+                console.log(`\n${installed ? "✓ Done - deps installed, wagmi + layout wired. Just run it:" : "Files written. Next:"}`);
+                if (!installed)
+                    console.log(`  ${result.install}`);
+                console.log(`  npm run dev`);
+                const openPath = wiring ? "" : route; // fresh scaffold serves the page at /
+                console.log(`  open http://localhost:3000${openPath}  and click Connect wallet (chainId ${chainId})`);
+                if (wiring)
+                    console.log(`  (also reachable at ${route})`);
+                console.log(`  ${result.network === "mainnet" ? "llama3-8b costs 0.02 LCAI per call" : "testnet is free"}`);
+                if (layoutNeedsManual) {
+                    console.log(`\nHeads up: couldn't auto-wire the layout (${layout?.reason}).`);
+                    console.log(`Wrap {children} with <Providers> in app/layout.tsx (import from "./providers").`);
                 }
-                else if (sub === "chat-web3" || sub === "inference-web3" || sub === "judge-web3") {
-                    // *-web3 variants have no PRIVATE_KEY (each visitor pays their own way).
-                    const needsWagmi = result.needsWagmi;
-                    const route = sub === "chat-web3" ? "/chat-web3"
-                        : sub === "inference-web3" ? "/inference-web3"
-                            : "/judge-web3";
-                    if (needsWagmi) {
-                        console.log(`  2. Get wagmi wired up with one command:`);
-                        console.log(`     npx lightnode add wagmi-setup`);
-                        console.log(`     (drops lib/wagmi.ts + app/providers.tsx + components/connect-button.tsx)`);
-                        console.log(`  3. Wrap your layout with <Providers> and drop <ConnectButton /> on the page.`);
-                        console.log(`  4. npm run dev, open ${route}, connect on chainId ${result.network === "mainnet" ? "9200" : "8200"}.`);
-                        console.log(`     Mainnet llama3-8b is 0.02 LCAI per call; testnet is free from https://lightfaucet.ai`);
-                    }
-                    else {
-                        console.log(`  2. npm run dev, open ${route}`);
-                        console.log(`  3. Connect a wallet on LightChain ${result.network === "mainnet" ? "mainnet (chainId 9200)" : "testnet (chainId 8200)"}.`);
-                        console.log(`     Mainnet llama3-8b is 0.02 LCAI per call; testnet is free from https://lightfaucet.ai`);
-                    }
-                    console.log(`\n  Note: ${sub} has NO server-side route, so it scales infinitely on`);
-                    console.log(`  static hosting (Vercel/Netlify/Cloudflare Pages free tier all work).`);
+                console.log(`\n  No server-side route - deploy static (Vercel/Netlify/Cloudflare free tier all work).`);
+            }
+            else if (sub === "wagmi-setup") {
+                console.log(`\n${installed ? "✓ Done - deps installed and layout wired." : "Files written. Run: " + result.install}`);
+                console.log(`\nUse it: import { ConnectButton } from "@/components/connect-button"; drop <ConnectButton /> anywhere.`);
+                console.log(`Any wagmi hook (useAccount, useWalletClient, ...) now works app-wide. Off-network wallets get a switch prompt.`);
+                if (layoutNeedsManual) {
+                    console.log(`\nHeads up: couldn't auto-wire the layout (${layout?.reason}). Wrap {children} with <Providers> in app/layout.tsx.`);
                 }
-                else if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat" || sub === "agent" || sub === "judge") {
+            }
+            else {
+                // server-paid + read-only targets keep the detailed guidance.
+                console.log(`\nNext steps:`);
+                console.log(`  1. ${installed ? "(done) " : ""}${result.install}`);
+                if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat" || sub === "agent" || sub === "judge") {
                     console.log(`  2. cp .env.example .env  (and put a funded ${result.network} PRIVATE_KEY in it)`);
                     if (sub === "agent" && result.template === "nextjs-api") {
                         console.log(`  3. Set CRON_SECRET in your Vercel env vars + edit AGENT_TASK in .env`);
@@ -638,8 +713,6 @@ async function main() {
                     }
                 }
                 // Hosting note: the Docker setup we shipped is the recommended path.
-                // The managed platforms (Vercel etc.) are the fallback if a builder is
-                // already committed to one.
                 if (result.template === "nextjs-api"
                     && (sub === "inference" || sub === "chat" || sub === "judge")) {
                     console.log(`\n  Hosting: a mainnet inference takes 60-90s. The Dockerfile + docker-compose.yml`);
@@ -648,13 +721,13 @@ async function main() {
                     console.log(`  Don't use Vercel Hobby (10s cap, every call times out). Vercel Pro works at`);
                     console.log(`  60s if you'd rather stay on Vercel. See LIGHTNODE-HOSTING.md for the full table.`);
                 }
-                if (result.network === "testnet") {
-                    console.log(`\nNo wallet yet? Make one:  npx lightnode wallet new   then fund it free below.`);
-                }
-                console.log(`\nFree testnet LCAI: https://lightfaucet.ai`);
-                console.log(`Builder docs:     https://lightnode.app/build`);
-                console.log(`New to all this?  See GETTING-STARTED.md in the lightnode repo.`);
             }
+            if (result.network === "testnet") {
+                console.log(`\nNo wallet yet? Make one:  npx lightnode wallet new   then fund it free below.`);
+            }
+            console.log(`\nFree testnet LCAI: https://lightfaucet.ai`);
+            console.log(`Builder docs:     https://lightnode.app/build`);
+            console.log(`New to all this?  See GETTING-STARTED.md in the lightnode repo.`);
             break;
         }
         case "batch": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.7.20",
+  "version": "0.8.1",
   "description": "Read-only TypeScript client for LightChain AI: workers, jobs, models, on-chain registration, and per-model network analytics. Independent, community-built (not an official LightChain package).",
   "type": "module",
   "main": "./dist/index.js",