> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mandala.md/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Run the stack, build the terminal, work with migrations, test agents, and preserve safety boundaries.

## Prerequisites

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

## Start the repository

```bash theme={null}
pnpm install --frozen-lockfile
supabase start
supabase db reset
cp .env.example apps/web/.env.local
pnpm seed
pnpm db:types
pnpm dev
```

On Windows PowerShell, use `Copy-Item .env.example apps/web/.env.local`.

The web app runs at [localhost:3000](http://localhost:3000). Local auth email appears in Inbucket at [127.0.0.1:54324](http://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

```bash theme={null}
pnpm cli:link
mandala auth login --local --email seed@example.com
mandala
```

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

```bash theme={null}
pnpm build
pnpm lint
pnpm typecheck
pnpm test
pnpm test:e2e

pnpm --filter web test
pnpm --filter @workspace/cli test
supabase test db
supabase db lint --local --level warning
```

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`.

```bash theme={null}
supabase db reset
pnpm db:types
supabase test db
```

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.

```bash theme={null}
cd docs
npx mintlify@latest validate
npx mintlify@latest broken-links
npx mintlify@latest dev
```

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:

```text theme={null}
docs/codex/runs/<yyyy-mm-dd-feature-slug>/
```

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.