Skip to main content

​
Prerequisites

  • Node.js 22 or newer
  • pnpm 10.33.x
  • Docker
  • Supabase CLI

​
Start the repository

On Windows PowerShell, use Copy-Item .env.example apps/web/.env.local. The web app runs at localhost:3000. Local auth email appears in Inbucket at 127.0.0.1:54324. The seed creates a development user, company, synthetic connector, capability grants, policy, catalog data, and test workflow state. Use pnpm seed:reset when you need to replace seeded state deliberately.

​
Terminal client

On macOS and Linux, the linker uses ~/.local/bin by default. On Windows it creates %LOCALAPPDATA%\Mandala\bin\mandala.cmd; add that directory to PATH or set MANDALA_BIN_DIR.

​
Common checks

Prefer the smallest relevant suite while iterating, then run the broader release-owned checks before handoff.

​
Database workflow

Schema changes are append-only SQL migrations under supabase/migrations.
Generated Supabase types are written to apps/web/lib/supabase/types.ts. Never hand-edit that file. Security-sensitive changes should add database tests for tenant isolation, anonymous access, role boundaries, expected-version conflicts, and replay behavior.

​
Agent development

  1. Start from an existing example in skills/.
  2. Keep the frontmatter contract declarative and versioned.
  3. Validate before installation.
  4. Test with synthetic fixtures.
  5. Test in real-data Sandbox and review generated mappings.
  6. Inspect the recommendation, evidence, warnings, draft, and history.
  7. Activate only after readiness passes.
Do not add a workflow-name branch, special API route, or extra privilege just to support one new agent. Extend the generic skill schema, capability catalog, compiler, or runtime only when the new concept truly applies across workflows.

​
Safety-sensitive code

When changing connectors, Context Engine, decisions, or execution:
  • preserve workspace scoping end to end;
  • validate at trust boundaries;
  • keep connector and model credentials server-only;
  • use expected versions for mutable configuration and review state;
  • make retries idempotent;
  • store evidence and audit history before side effects;
  • retain fail-closed behavior for missing grants, stale data, schema drift, and unhealthy providers; and
  • test direct API bypass attempts, not only the guided CLI.

​
Documentation

Mintlify source lives under docs/ in the repository.
Update documentation in the same change when commands, environment variables, route contracts, lifecycle states, or safety boundaries change.

​
Codex and design workflow

Repository instructions live in AGENTS.md and CLAUDE.md. Figma-to-implementation and release-ready feature work uses the repo-owned Orchestrator skill. Review artifacts belong under:
The design contract is an approval gate. Before merge or release, remove temporary contracts, plans, QA notes, and fix lists unless they are intentionally durable documentation.