Merge branch 'main' into feat/office-systems-next

AGENTS.md

@@ -9,3 +9,33 @@ Do not modify the OpenClaw source code. When the user asks for changes, they are
 If you use local private overlay instructions, keep them outside the repository and do not commit them here.
 
 Do not commit personal, environment-specific, or secret instructions to this repository.
+
+## Cursor Cloud specific instructions
+
+### Service overview
+
+Claw3D is a Next.js 16 frontend (TypeScript, React 19, Three.js, Phaser) for OpenClaw. It runs a custom Node.js server (`server/index.js`) that bundles a same-origin WebSocket proxy to the upstream OpenClaw Gateway. No database or Docker is required. The only hard system dependency is Node.js 20+ with npm 10+.
+
+### Running the app
+
+- `npm run dev` starts the dev server on port 3000 via the custom server (`node server/index.js --dev`).
+- The app requires a running OpenClaw Gateway to show agent data. Without one, the UI loads but shows the gateway connection form. This is expected and not an error.
+- `.env` is copied from `.env.example`; see `README.md` "Configuration" for variable descriptions.
+
+### Lint, typecheck, and tests
+
+- `npm run lint` — ESLint. The codebase has a small number of pre-existing warnings and one pre-existing error (in `RetroOffice3D.tsx`).
+- `npm run typecheck` — `tsc --noEmit`. Pre-existing type errors exist in some test files (`agentChatPanel-*.test.ts`) due to a stale `onOpenSettings` prop.
+- `npm run test -- --run` — Vitest unit tests (use `--run` for single-run mode). A few pre-existing failures exist.
+- `npm run e2e` — Playwright E2E tests; requires `npx playwright install` first.
+- `npm run smoke:dev-server` — starts the dev server on a random port and verifies HTTP response.
+
+### Build
+
+- `npm run build` — Next.js production build. Expect a non-blocking warning about `Can't resolve 'openclaw'`; the `openclaw` npm package is resolved optionally at runtime and is not bundled.
+
+### Gotchas
+
+- The `openclaw` npm package is not a dependency of this repo. The build warning about it is harmless.
+- `npm run studio:setup` is interactive (TTY prompts) — avoid running it in non-interactive cloud environments.
+- Vitest runs in watch mode by default; always pass `--run` for CI/cloud agent use.

Dockerfile

@@ -0,0 +1,34 @@
+# Claw3D - 3D agent visualization for OpenClaw.
+# Multi-stage build: install prod deps -> build Next.js -> run with custom server.
+
+FROM node:20-slim AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts --omit=dev
+
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+# Build-time gateway URL (overridden at runtime by CLAW3D_GATEWAY_URL).
+ENV NEXT_PUBLIC_GATEWAY_URL=ws://127.0.0.1:18789
+RUN npm run build
+
+FROM node:20-slim AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+# Copy built app + custom server + production node_modules only.
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/server ./server
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/next.config.ts ./next.config.ts
+
+EXPOSE 3000
+
+CMD ["node", "server/index.js"]