# Braith: coding-agent integration guide

Braith reviews sampled customer activity across supported web-app surfaces, including flows without configured outcomes. Use it when a successful request or completed job does not establish that the customer got the intended result: paid access, usable exports, workspace creation or accepted invitations.

Keep an error tracker for exceptions and stack traces. Braith is not automatic session replay, a repository scanner or a native mobile SDK. Missing completion telemetry alone is not failure evidence.

## Start with the customer's account

The setup instructions are public and identical for everyone: https://app.braith.dev/setup.txt. Run braith connect, show the owner its authorization link and code, and wait for approval in their signed-in Braith account. Credentials travel separately to the waiting CLI and never belong in the prompt.

Pro is £59/month total. Free is available without a card. Connecting does not activate paid billing; paid activation is an explicit customer action. Never activate billing on the customer's behalf without their instruction.

## Supported packages and CLI

Official npm packages: braith@0.3.0 and @braith/sdk@0.2.0. Inspect repository conventions before changing dependencies or code.

1. Install @braith/sdk with the repository's package manager.
2. Run npx braith@0.3.0 connect. Show the authorization link and code to the owner. Inspect braith.config.json and .braith/SETUP.md after approval.
3. Connect again to renew expired setup access; existing credentials survive failed renewal. Never print or commit credentials.
4. Install supported discovery capture and a static context catalogue across the app in review mode. Add stronger core outcome checks where useful; do not require predefined flows for discovery. Exercise real normal, failed and recovered interactions.
5. Run npx braith@0.3.0 validate. Review errors, warnings and source checks that could not be verified.
6. Present the changes for review. After the required review, run npx braith@0.3.0 push and, when configured core outcomes exist, npx braith@0.3.0 test. The latter creates isolated test evidence; it does not prove production connectivity. Use test --semantic only when that check is needed, not in an unbounded retry loop.
7. Bind the reviewed configuration with npx braith@0.3.0 release <build-id>. Use the same release in the SDK. Use release default explicitly only if build IDs are unavailable.
8. The customer deploys through their normal process. Do not upload their repository or deploy automatically. Verify real production events from a configured task after deployment.

## Evidence and trust

Use createServerClient from @braith/sdk for authoritative server facts. Browser code uses Braith.init, Braith.identify and Braith.track. Server track calls require an explicit subject context. Send one attemptId through related browser and server steps.

Browser events cannot prove payment or entitlement. Use scoped browser keys in public code; keep server keys and temporary management keys on the server or in ignored local files. Enrollment stores credentials in .braith/credentials.json with a local ignore rule. Temporary setup-management access expires after 30 minutes.

Declare event names, allowed properties, success boundaries, correlation and explicit contradictions in the manifest. Check what the app can observe; a download click does not establish file delivery. Treat absent evidence as unknown. Respect grace periods, legitimate cancellations and valid empty results.

Do not send emails, tokens, card information, form values, full webhook payloads or arbitrary request bodies. The SDK sends bounded sanitised observations and configured events, not the repository or every interaction.

## API discovery

Base URL: https://app.braith.dev
OpenAPI 3.1: https://app.braith.dev/openapi.json

- POST /api/v1/setup starts an expiring device connection or polls it. Only the waiting CLI with the private device token receives scoped keys after explicit signed-in approval. Poll no faster than every five seconds.
- POST /api/v1/enrollment/redeem supports legacy one-use enrollment tokens. New setup uses connect.
- POST /api/v1/manifest publishes a validated manifest using temporary management credentials. It does not silently activate a new release.
- POST /api/v1/releases binds a reviewed manifest version to a release. An existing build binding cannot be reassigned to a different manifest.
- POST /api/v1/events accepts batches of 1–100 explicitly defined events with a scoped ingest key. Use the SDK unless implementing a deliberate custom integration.
- POST /api/v1/test starts an isolated configured integration check. GET /api/v1/test?runId=<id> checks its result. Both require temporary management credentials.

## Limits and errors

Read each API response, including per-event results. HTTP 200 for a batch does not mean every event was accepted. Events are limited to 4 KiB each, with at most 24 properties and 1 KiB of properties. The batch body limit is 1 MiB. Raw manifest requests are limited to 256 KiB and the validated manifest has a 64 KiB delivery limit. Other semantic checks are performed by the service and CLI, beyond the JSON schema.

For 401, check scope, revocation and expiry; run braith connect again for expired setup access. For 400 or 413, correct the request rather than retrying it unchanged. For 409, review manifest/release conflicts instead of overriding them. Respect Retry-After on 429, use bounded backoff and stop when a plan allowance is exhausted. Do not let telemetry block the customer's primary action.

## What is not offered

No public MCP server, incident-reading API or autonomous account-management API is currently offered. These documented APIs support integration and event ingestion; they do not grant access to a customer's private incidents. Account billing, deletion and key rotation remain protected customer actions in Braith.

## Report honestly

Report separately: code instrumented, configuration validated, manifest published, release bound, test evidence checked, deployment completed and real production events received. A copied prompt, successful test or missing errors is not proof that the app is connected or healthy.

## Further reading

- Product: https://app.braith.dev/how-it-works
- Pricing and actual allowances: https://app.braith.dev/pricing
- Next.js: https://app.braith.dev/docs/nextjs
- Free customer-flow tests: https://app.braith.dev/tools/user-flow-tests
- Support: https://app.braith.dev/support