# Capxul Sandbox (`@capxul/sandbox`)

The published interactive CLI for two sandbox operator/developer tasks:

- `key create` mints a test publishable key for a local origin and writes the
  canonical Next.js environment names to `.env.local`.
- `faucet send` mints test USDC on Base Sepolia to a Capxul email,
  `@org-handle`, or an explicitly confirmed raw-address escape hatch.

```bash
npx @capxul/sandbox key create
npx @capxul/sandbox faucet send

# Repository development
vp run --filter @capxul/sandbox dev -- --help
```

`key create` uses the Openship public staging Site endpoint and
needs no operator secret. `APP_ENV` does not retarget this public command; use
the returned key only with the staging tuple.
`faucet send` invokes the canonical Convex deployment and requires operator
access in the process environment: inside the infrastructure repository, run
it through the one env entry point
(`APP_ENV=staging vp exec bash packages/tools/src/bin/capxul-env.sh npx @capxul/sandbox faucet
send`); outside it, supply the self-hosted admin key directly
(`CONVEX_SELF_HOSTED_ADMIN_KEY=… npx @capxul/sandbox faucet send`). Never print
or commit that value.

The faucet reads the test USDC identity and precision from the public Core SDK
asset catalog. It does not copy the token address or decimal scale.

## Verify in the repository

```bash
vp run --filter @capxul/sandbox check-types
vp test run apps/sandbox
vp run --filter @capxul/sandbox build
```

These checks prove parsing, environment-file rewriting, bounded amount
conversion, Convex command construction, and packing. They do not prove a live
key mint, faucet transaction, or installed CLI artifact.

The historical [#920](https://github.com/Xelmar-tech/infrastructure/issues/920)
plan names a `proofs:live` command that this package does not define. Check the
current issue and proof state before selecting live acceptance.
[#922](https://github.com/Xelmar-tech/infrastructure/issues/922) records the
separate packed-install and bin startup proof requirement. The current
`packages/tools/src/modules/release/release.pack-install.test.mjs` installs the CLI tarballs in a
clean project and invokes their bins with `--help`. Its current run result
owns that artifact claim; it does not prove a live key mint or faucet transfer.

Read [CONTEXT.md](./CONTEXT.md) before changing command, secret, deployment, or
proof behavior.