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, APIs, route contracts, lifecycle states, user workflows, safety boundaries, or operating procedures change. Orchestrator reviews the complete Mintlify diff and preview, runs npx mintlify@latest validate plus npx mintlify@latest broken-links, deploys through the configured production workflow, and verifies the live page. A staged branch, preview, or open documentation PR is not completion. Internal changes with no reader-visible documentation impact do not require a docs edit or deployment. Mintlify is also a context source at the beginning of an Orchestrator run. When the requested surface is likely documented, Orchestrator searches the connected Mintlify site, reads the relevant full pages, and records which documented expectations informed the contract. It compares those pages with current code, migrations, runtime evidence, plans, and designs. Verified code and runtime establish current behavior; conflicts are recorded as documentation drift instead of silently treating stale docs as authoritative.

​
Codex and design workflow

Repository instructions live in AGENTS.md and CLAUDE.md. Design-to-implementation, bugfix, and release-ready work uses the repo-owned Orchestrator skill. Review artifacts belong under:
The design or bugfix contract is an approval gate. Before merge or release, remove temporary contracts, plans, QA notes, and fix lists unless they are intentionally durable documentation. For production-facing fixes and releases, Orchestrator records Code, Deployment, Database, Real Data, and External Provider independently. A passing test suite or deployment does not prove the real-data journey or provider health; every applicable layer must pass or be explicitly deferred.