Add one-click NovaSpine setup for existing OpenClaw installs

README.md

@@ -89,6 +89,34 @@ Prerequisite:
 - For a no-framework local office demo, run the bundled demo gateway instead.
 - If you need a full cross-machine setup guide (OpenClaw + Tailscale + Claw3D), follow [`TUTORIAL.md`](TUTORIAL.md).
 
+### One-click NovaSpine for existing OpenClaw installs
+
+If you already use OpenClaw, Claw3D can wire NovaSpine into that install for you from the onboarding flow or the gateway connection panel.
+
+What Claw3D does in that setup flow:
+
+- detects your local OpenClaw CLI and config
+- checks that Python 3.12+ is available
+- installs a pinned NovaSpine Python package version
+- copies the bundled NovaSpine OpenClaw integration assets that ship with Claw3D
+- patches your OpenClaw config to use NovaSpine memory and context slots
+- validates the updated OpenClaw config
+
+What stays the same:
+
+- your OpenClaw install
+- your model/provider setup
+- your gateway URL and token flow
+
+What improves:
+
+- long-term memory and recall
+- context injection
+- consciousness/dream/wiki surfaces exposed by the NovaSpine-backed OpenClaw path
+- stronger personal-memory retrieval and current-state recall in the bundled NovaSpine release
+
+See [`docs/integrations/novaspine-openclaw.md`](docs/integrations/novaspine-openclaw.md) for the exact flow and requirements.
+
 Run from source:
 
 ```bash

docs/integrations/novaspine-openclaw.md

@@ -0,0 +1,59 @@
+# NovaSpine + OpenClaw in Claw3D
+
+Claw3D can attach NovaSpine to an existing local OpenClaw install without asking the user to install NovaSpine separately first.
+
+## Intended User Flow
+
+1. The user installs Claw3D.
+2. The user already has OpenClaw on the machine.
+3. Claw3D detects that OpenClaw install during onboarding or from the gateway settings panel.
+4. The user clicks `Enable NovaSpine`.
+5. Claw3D installs and validates the NovaSpine integration against that OpenClaw config.
+
+From the user's point of view, they installed Claw3D and got NovaSpine memory in the same flow.
+
+## Requirements
+
+- OpenClaw already installed locally
+- a reachable local OpenClaw config, typically `~/.openclaw/openclaw.json`
+- Python 3.12+
+- network access is optional; Claw3D prefers the bundled pinned NovaSpine wheel when it is present
+
+## What Claw3D Installs
+
+Claw3D does not bundle a second runtime. It upgrades the user's existing OpenClaw setup by:
+
+- installing a pinned NovaSpine Python package version from the bundled wheel when available
+- copying the bundled NovaSpine OpenClaw integration assets that ship with Claw3D
+- forcing the OpenClaw config onto NovaSpine's memory and context slots
+- validating the final config
+
+In the current Claw3D bundle, the OpenClaw-side assets and bundled Python wheel are pinned to NovaSpine `0.3.3` and include the OpenClaw `2026.4.12`-compatible plugin snapshot plus the FAISS dedupe fix, safer oversized-chunk backfill, embedding-cache scoping fixes, and the newer personal/current-state retrieval improvements.
+
+## What This Enables
+
+Once the integration is active, the user's existing OpenClaw setup can benefit from:
+
+- NovaSpine memory recall
+- NovaSpine context injection
+- NovaSpine-backed consciousness surfaces
+- dream/wiki/facts features exposed through the NovaSpine path
+
+Claw3D itself stays the UI/control layer. OpenClaw remains the runtime. NovaSpine becomes the memory/context layer attached to that runtime.
+
+## What Stays the Same
+
+- the user's OpenClaw install
+- the user's model/provider configuration
+- the gateway URL/token connection flow inside Claw3D
+- the existing bootstrap files such as `SOUL.md`, `IDENTITY.md`, and `MEMORY.md`
+
+## Scope
+
+This first-pass integration is intentionally backend-first:
+
+- it enables NovaSpine in the runtime
+- it reports setup state in Claw3D
+- it does not yet add dedicated recall/wiki dashboards inside the UI
+
+Those richer UI surfaces can be added later without changing the integration shape.

src/app/api/novaspine/route.ts

@@ -0,0 +1,42 @@
+import { NextResponse } from "next/server";
+
+import {
+  getNovaSpineIntegrationStatus,
+  installNovaSpineIntoOpenClaw,
+} from "@/lib/novaspine/integration";
+
+export const runtime = "nodejs";
+
+type InstallRequest = {
+  action?: string;
+};
+
+export async function GET() {
+  try {
+    const status = getNovaSpineIntegrationStatus();
+    return NextResponse.json({ status }, { headers: { "Cache-Control": "no-store" } });
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Failed to inspect NovaSpine integration state.";
+    console.error(message);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}
+
+export async function POST(request: Request) {
+  try {
+    const body = ((await request.json().catch(() => ({}))) ?? {}) as InstallRequest;
+    const action = typeof body.action === "string" ? body.action.trim() : "install";
+    if (action !== "install") {
+      return NextResponse.json({ error: `Unsupported action: ${action}` }, { status: 400 });
+    }
+    const result = installNovaSpineIntoOpenClaw();
+    const statusCode = result.ok ? 200 : 500;
+    return NextResponse.json(result, { status: statusCode, headers: { "Cache-Control": "no-store" } });
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Failed to install NovaSpine into OpenClaw.";
+    console.error(message);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

src/features/agents/components/ConnectionPanel.tsx

@@ -1,6 +1,7 @@
 import type { GatewayStatus } from "@/lib/gateway/GatewayClient";
 import type { StudioGatewayAdapterType } from "@/lib/studio/settings";
 import { X } from "lucide-react";
+import { NovaSpineSetupCard } from "@/features/agents/components/NovaSpineSetupCard";
 import { resolveGatewayStatusBadgeClass, resolveGatewayStatusLabel } from "./colorSemantics";
 
 type ConnectionPanelProps = {
@@ -151,6 +152,7 @@ export const ConnectionPanel = ({
           {error}
         </p>
       ) : null}
+      {selectedAdapterType === "openclaw" ? <NovaSpineSetupCard compact /> : null}
     </div>
   );
 };