KrabiClaw

KrabiClaw runs the website, bookings, payments and messaging for restaurants, experience operators, law firms and lodging hosts, managed from the dashboard or from ChatGPT and Claude through one MCP service. Lodging includes homes, nightly availability and prices, direct stay bookings and guest messaging.

Open source under AGPL-3.0.

• Report a bug or request a feature: open an issue. Assistants filing for a user can prefill the form; see the field ids in .github/ISSUE_TEMPLATE.
• Account, billing or private data: krabiclaw.com/help.
• Security: SECURITY.md.
• Contributing: CONTRIBUTING.md.

Nuxt 5 nightly + Nitro 3 + Cloudflare Workers + D1.

Package manager: yarn only. Never npm or pnpm.

---

Scripts

Command	What it does
yarn dev	Nuxt development server with HMR and locally emulated Cloudflare bindings at http://localhost:3000.
yarn local:setup	Reset local Wrangler state and migrate an empty local D1.
yarn local:seed	Build the synthetic E2E businesses in the running local Worker.
yarn dev:worker	Build and run the production-like Worker locally with Wrangler at http://localhost:3000.
yarn dev:worker:start	Run the existing .output Worker build locally without rebuilding it.
yarn build	Production build → .output/
yarn db:generate	Generate a new migrations/*.sql file from server/db/schema.ts
yarn drizzle:check	Verify server/db/schema.ts hasn't drifted from the live D1 schema
yarn stripe:listen	Forward Stripe webhooks to localhost (local dev only)
yarn canary:prod	Production-safe authenticated browser canary (read-only checks).
yarn canary:notifications	Production provider-level email/WhatsApp notification canary.

---

Production Canary Runs

Real-send production canaries are intentionally off on normal main deploys to avoid accidental email/WhatsApp spend on every merge. To run them on demand, use the GitHub Actions workflow Production Real-Send Canaries and choose whether to send:

• the auth OTP canary
• the notification email/WhatsApp canary

That workflow always runs production smoke first, then only sends the real canaries you explicitly selected for that run.

See docs/notification-testing.md for the full policy on log-only vs live email/WhatsApp testing, production-safe verification, and which public submission paths send for real in production.

---

Local Setup

1. Install

corepack yarn install

The repository uses Node.js 24.18.1. Use the exact version declared in .nvmrc before installing dependencies. When changing Node, follow the Node runtime upgrade runbook so local development, CI, type definitions, and Worker builds move together.

Yarn accepts new direct and transitive package releases only after seven days. Routine yarn add and yarn up commands apply this rule automatically. CI installs the package graph immutably and rechecks registry metadata in its hardened job.

For an urgent reviewed security fix, update only the affected package:

corepack yarn up <package>@<fixed-version> --no-time-gate

Record the advisory and the reason for bypassing the wait in the pull request. Do not add a package to npmPreapprovedPackages or disable the age gate in .yarnrc.yml.

2. Environment

Copy .env.example to .env and fill in the application secrets there. This is the single local configuration for Nuxt, Wrangler, setup scripts, and E2E tests. See local development for setup and migrating an older .dev.vars file. No second secret file or symlink is needed.

3. Prepare local development

corepack yarn local:setup

It leaves an empty local D1 at the current migration. Start the app (step 4), then build the synthetic businesses Playwright also uses:

corepack yarn local:seed

Sign in at /login as [email protected] with E2E_PASSWORD from config/development-auth-fixtures.ts: a Better Auth admin who owns every seeded business.

4. Run

corepack yarn dev

App at http://localhost:3000.

yarn dev is the normal application-development loop. Nitro reads the bindings declared in wrangler.toml, emulates local D1/KV/R2 resources, and preserves Nuxt hot module replacement. It never resets D1. Run corepack yarn local:setup and corepack yarn local:seed again to start over.

Open tenant dashboards from the dashboard UI instead of guessing their URLs. When a route must be constructed manually, the dashboard segment is the organization's slug, not its subdomain, and everything else sits directly under it: Kikuzuki's locations are /dashboard/org-bVY8SxxUuG6Ctk2CQnfCk8T2cPsj4jJX/locations.

For production-runtime browser verification, use the generated Worker locally. Wrangler reads the same .env as Nuxt. Playwright also loads it and supplies test-specific local URLs and delivery settings to the Worker.

yarn test:e2e:local tests/e2e/tenant-content.spec.ts

For a production-like local Worker:

yarn dev:worker

After a successful build, yarn dev:worker:start restarts that same .output without rebuilding. Source edits are not compiled into .output automatically; use yarn dev for the normal HMR editing loop.

Playwright applies the local D1 schema to an empty database, builds the Cloudflare Worker, starts it under local workerd, and seeds the synthetic businesses through the app's own boundaries (tests/e2e/seed). Authenticated tests sign in through Better Auth as the seeded fixtures; no email inbox or authentication bypass route is involved.

Local tenant tests use a shared-host routing contract: the browser targets localhost and the test helper supplies x-preview-tenant for the selected fixture. Deployed staging uses direct first-level tenant aliases instead. This is the authoritative local browser path; do not rely on direct *.localhost navigation for Worker browser verification.

http://localhost:3000/                  (x-preview-tenant: harbor-legal)
http://localhost:3000/services          (x-preview-tenant: harbor-legal)
http://localhost:3000/experiences       (x-preview-tenant: clayhouse)
http://localhost:3000/reservations      (x-preview-tenant: demo)

macOS file limit fix

ulimit -n 65536

---

Deployment

Deployment follows the branches in .github/workflows/ci.yml:

1. Pull requests run Checks and the E2E suite against a local Worker and a local D1 seeded with synthetic businesses (tests/e2e/seed). Nothing is deployed for a pull request, and no production data is read.
2. Pushes to staging run Checks, then deploy the staging Worker, apply staging migrations, and run read-only MCP and tenant rendering against staging itself. Nothing writes test data into real staging.
3. Pushes to main run Checks, then deploy the production Worker, apply production migrations, and run read-only production browser verification.

CI invokes native Wrangler commands only in the matching branch job.

During an incident, use Cloudflare's deployment history to restore the last known-good production deployment without changing D1 data. Then land the source fix through staging and main and repeat the browser gates.

Production secrets live in the Cloudflare dashboard → Workers & Pages → krabiclaw → Settings → Variables.

Set protected internal job secrets with Wrangler:

openssl rand -base64 32
yarn wrangler secret put CRON_SECRET

CRON_SECRET protects internal scheduled endpoints. Local commands read their configuration from .env; deployed Workers use Cloudflare secrets and the variables in wrangler.toml.

MCP reconnect triage and Cloudflare auth debugging are documented in docs/observability.md.

The mandatory deployed-browser release gate and outage recovery rules are documented in docs/operations/release-and-outage-prevention.md.

---

Schema

server/db/schema.ts is the only schema source of truth; migrations/ holds generated output. Hand-written migrations are prohibited.

---

Stripe (local)

yarn stripe:listen

Copy the whsec_... signing secret it outputs into .env as STRIPE_WEBHOOK_SECRET. Swap back to the production webhook secret before deploying.

Native marketplace onboarding uses a separate Accounts v2 thin-event destination and signing secret. See Stripe Connect onboarding.