Local development and testing

This guide is for contributors running the Supervisible application. Use a disposable database with synthetic data. Confirm both the application and migration connections point to that database before running setup or write tests. Never assume a local web server implies a local database.

Connect a local client

With the app running at http://localhost:3000, configure a separate development connection:

codex mcp add supervisible-local --url http://localhost:3000/api/mcp
codex mcp login supervisible-local

Or use Claude Code:

claude mcp add --transport http supervisible-local http://localhost:3000/api/mcp

In Claude Code, open /mcp and authenticate. In either client, complete sign-in and workspace consent, then call whoami. The app's configured origin and OAuth metadata must match the development URL. Use your actual port consistently.

No tunnel is needed when the client and app run on the same machine. A client running in a container, remote development host or cloud has a different network context. Claude's hosted custom connectors connect from its cloud infrastructure; ChatGPT also needs an endpoint it can reach. Use a properly configured HTTPS development endpoint or supported tunnel for those tests, then reconnect using its URL. See Claude's connector guide and OpenAI's connection guide.

Acceptance checks

Use two workspaces and at least an admin, an ordinary member and a freelancer. Seed people, a project, assignments, compensation periods and leave.

1. Complete actual OAuth sign-in, workspace selection and tool discovery.
2. Run whoami and read a known record. Confirm a foreign-workspace ID is unavailable.
3. Exercise an allowed write as a preview. Verify that no record changed. Apply deliberately and read it back.
4. Repeat with a member who lacks permission. Verify denial or appropriate field redaction.
5. Change the connected member's permissions and repeat the request without relying on an old session snapshot.
6. Change web workspaces and confirm the existing grant stays bound to the original membership.
7. Test ambiguous names, invalid fields, stale revisions and partial import results.
8. Revoke the connection and verify it stops working. Check configured notification/calendar effects separately when testing writes that cause them.

Repository checks

From apps/app, after verifying test database configuration:

pnpm test:setup
pnpm test:unit
pnpm test:integration
pnpm check-types
pnpm lint

From the repository root, pnpm signoff:local runs the full local gate, including browser tests and the runtime-log audit. Review its report in test-results/local-signoff. Use isolated test credentials; do not include them in docs or screenshots.

Local acceptance is evidence for that build and environment. It does not establish hosted-client compatibility or directory approval. Use the reviewer guide for the remaining hosted checks.