KrabiClaw

KrabiClaw runs the website, bookings, payments and messaging
for restaurants, experience operators and professional-service businesses, managed from
the dashboard or from ChatGPT and Claude through one MCP service.

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

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

The command is safe to repeat. It leaves local D1 at the current migration,
fixture, credential, and foreign-key baseline, then prints the one local
developer login:

URL: http://localhost:3000/login?email=developer%40playwright.example
Email: [email protected]
Password: <fresh value generated by local:setup>

This localhost-only account is a member of every curated tenant and can access
the platform dashboard. The password is generated on each setup run, printed
once, and stored only as a hash in local D1. A repeated setup deletes existing
local sessions, so sign in again with the newly printed password afterward.

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 when you want to restore local D1 from a production
snapshot.

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-rendering.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, clears disposable E2E artifacts, restores
a production snapshot, provisions verified synthetic Better Auth accounts, builds the
Cloudflare Worker, and starts it under local workerd. Authenticated tests sign
in through Better Auth with a random password generated inside the Playwright
process; no email inbox or authentication bypass route is involved. Those test
credentials are not a second manual login path. Use the local developer account
printed by corepack yarn local:setup for browser work.

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: ncls)
http://localhost:3000/services          (x-preview-tenant: ncls)
http://localhost:3000/experiences       (x-preview-tenant: pottery-house)
http://localhost:3000/reservations      (x-preview-tenant: kikuzuki-krabi-thailand)

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 copied from production (db:pull:local). Nothing is deployed for a
   pull request.
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.