README

# maoclaw Web

This directory contains the official web surface for `maoclaw / 猫爪`.

It exists to support the public open-source product story:

- official brand presentation
- docs and release entrypoints
- install and upgrade guidance
- web control-plane surfaces that align with the same Rust runtime
- vertical agent customization and operator-facing workflows

Community nickname in Chinese: `机器猫`

Official public identity remains `maoclaw / 猫爪`.

## What is included

- product-aligned technical architecture for the web control plane
- local bridge protocol aligned to `maoclaw --mode rpc`
- Next.js app scaffold for the public surface and app shell
- Prisma schema for core control-plane entities
- Docker Compose for local Postgres, Redis, MinIO, and Mailpit
- typed demo APIs for bridge linking, heartbeats, systems, tasks, and task events
- public install and onboarding flows aligned to `miounet11/maoclaw`

## Local setup

1. Copy `.env.example` to `.env`.
2. Start infrastructure with `docker compose up -d`.
3. Install dependencies with `pnpm install` or `npm install`.
4. Start the app with `pnpm dev` or `npm run dev`.
5. For database-backed mode, use `npm run dev:prisma` after migrations and seed complete.

## Current backend mode

The API layer currently runs on an in-memory demo store so the control-plane flows can be built before Prisma-backed repositories are wired in.

Set `CONTROL_PLANE_DRIVER=prisma` only after Prisma migrations and repository implementation are ready.

The schema and initial migration are now present, but the route layer still uses the memory driver by default until async Prisma-backed route plumbing is completed.

Use `npm run doctor` to check Docker daemon reachability and the expected local service ports.

## Documentation

- Active public/trial docs live under `docs/maoclaw-v0.1/`.
- Historical legacy planning material is kept under `docs/archive/` for internal reference only.
- The production deployment runbook is `maoclaw-production-deploy-runbook.md`.

## Immediate next implementation targets

1. Add real auth.
2. Implement bridge linking endpoints and websocket session management.
3. Add Prisma migrations and seed data.
4. Replace mock dashboard data with database-backed queries.