Dev onboarding

Get productive in the Xelmar-tech/infrastructure monorepo — prerequisites, the vp toolchain, workspace layout, and where the canon lives.

This section is for developers joining the platform repository — Xelmar-tech/infrastructure (local checkouts are often named capxul-platform) — as contributors. These pages summarize the repo's internal canon and link into it; when a page here disagrees with a canon file in the repo, the canon file wins.

Start with this page, then read Architecture, Conventions, and Release flow.

Prerequisites

Node ≥ 22.12 — enforced by the root package.json engines field. The vp and convex CLIs break on older Node.
pnpm 9.15.9 — pinned via the root packageManager field.

git clone git@github.com:Xelmar-tech/infrastructure.git
cd infrastructure
pnpm install   # also installs the lefthook git hooks

The vp toolchain

The repo runs on vite-plus (vp). Every gate-shaped command goes through a vp verb — raw pnpm and bare bash scripts/*.sh invocations are banned by the repo's operating rules (AGENTS.md Rule 3). The task graph that the aggregate gates traverse is defined in the root vite.config.ts under run.tasks.

Command	What it does
`vp test`	Hermetic unit tests (Vitest) — no external services, no secrets file
`vp lint --deny-warnings`	Lint (oxlint, not ESLint)
`vp run lint:fix`	Lint with auto-fix
`vp run format`	Format (oxfmt, not Prettier)
`vp run check-types`	`tsc --noEmit` against the root project
`vp run check:fast`	The pre-push gate (lefthook runs it for you)
`vp run check:full`	The full gate — runs on pushes to `master` in CI; includes `vp pack`
`vp run test:e2e`	Live SDK e2e against a real deployment (sources operator secrets itself)

Fan-out and targeting: vp run -r <task> runs a task across packages, vp run --filter <pkg> <task> targets one. Libraries build with vp pack, apps with vp build.

Workspace layout

A pnpm monorepo with two workspace groups. packages/*:

Package	One line
`@capxul/sdk`	Core TypeScript client — `createCapxulClient` and method bundles (published)
`@capxul/sdk-react`	React hooks over the client (published)
`@capxul/sdk-testing`	Test utilities for SDK adapters and proof harnesses (published)
`@capxul/backend`	Convex backend — schema, auth, credentials, tenancy (private)
`@capxul/wire`	Wire schemas shared by backend and SDK adapters (private)
`@capxul/types`	Branded domain types and their `to*` constructors (private)
`@capxul/errors`	`CapxulError` factories and Convex error decoding (private)
`@capxul/config`	Chain configs and constants (private)
`@capxul/observability`	Telemetry utilities (private)
`@capxul/contracts`	Solidity settlement contracts, built with Foundry (private)

apps/*:

App	One line
`apps/mcp`	The Capxul MCP server CLI — agent-facing financial-ops tools (published)
`apps/sandbox`	Sandbox operator CLI — publishable keys and testnet faucet (published)
`apps/docs`	This documentation site (Fumadocs)
`apps/reference`	Canonical SDK consumer exemplar app
`apps/exemplar`	Greenfield SDK integration DX demo
`apps/approve`	One-page approval app that MCP approval links deep-link into
`apps/skybridge`	React views over the SDK, rendered inside ChatGPT/Claude

Which packages publish to npm and which never do is covered in Release flow.

Where the canon lives

The repo's standing rules live in canon/ at the repo root:

canon/conventions/ — load-bearing conventions: branded types, error handling, the test contract, and more (summarized in Conventions).
canon/rules/ — short, enforceable rules (public surface, branded types, vocabulary discipline).
canon/ports/ — one spec per port in the ports-and-adapters seam.
canon/vocabulary/ — the port, brand, and error catalogs.
canon/architecture.md, canon/release-flow.md, canon/dev-onboarding.md — the architecture contract, the publish runbook, and the operational onboarding guide.

CONTEXT.md at the repo root is the domain glossary and the vocabulary authority. When a term there disagrees with the code, the disagreement is a bug in one of them — say so.

Backend, keys, and secrets

Day-to-day development runs against a Convex deployment. The recommended path is an isolated per-worktree deployment: bash scripts/provision-agent-convex.sh creates one, sets its server env, pushes the backend, and mints a publishable key. Operator secrets live in one file per machine — ~/.config/capxul/secrets.env — managed with vp run secrets:init and vp run secrets:verify (never commit or print values). The full operational guide — origin allowlists, the dev OTP peek, and the gotchas that cost real time — is canon/dev-onboarding.md.

Agents work here too

The repo is operated by humans and autonomous agents under the same rules. AGENTS.md carries the closed-loop operating rules that apply to every agent in every runtime: decision prompts must carry a full decision pack (ground-truth code or diagram, rubric, graded options, recommendation); every PR must pass a clean run of the local /code-review gate before it is opened; and every gate-shaped invocation goes through vp, never raw pnpm or shell scripts. Read it before dispatching or acting as an agent in this repo.