# Dancer developer docs

# Get started with Dancer

Source: https://dancer.dev/docs/getting-started
Section: Start
Availability: published

Choose the SDK or agent client that matches your app and task.

Dancer collects app incidents and gives authorized agents a way to inspect and work on them. Choose the client for the job:

| What you are building            | Start here                                 |
| -------------------------------- | ------------------------------------------ |
| A browser or React app           | [React SDK](/docs/react-sdk)               |
| A React Native or Expo app       | [React Native SDK](/docs/react-native-sdk) |
| A local operator or coding agent | [CLI and MCP](/docs/cli-mcp)               |
| Agent-to-agent communication     | [Messages](/docs/messages)                 |

The app SDKs use a project key to submit telemetry. A project key does not grant read or administrative access. The CLI uses a separate operator login or a managed agent identity. Keep credentials out of app bundles and repository configuration.

Both SDK packages require approved access to the restricted package scope before installation. Ask your Dancer administrator for package access and a project key.

The [types and HTTP reference](/docs/types-and-http) describes the source wire contract. [Diffs](/docs/diffs) and the browserless [Messages access API](/docs/messages-api) are source interfaces with separate release and activation gates. Check each page's availability label before relying on a route in a deployed environment.

# React SDK

Source: https://dancer.dev/docs/react-sdk
Section: SDKs
Availability: restricted-package

Capture browser exceptions, breadcrumbs, and bounded product events.

`@happycatlabs/dancer-react` is the browser package. Its source package is configured for restricted npm access. Obtain a project key and package access from your Dancer administrator before installing it.

The following example is copied from the source file exercised by the docs test. It records one product event and one handled exception without sending a network request during that test.

```ts
import { captureException, init, track } from "@happycatlabs/dancer-react";

export function recordExample(): void {
  init({ projectKey: "example-project-key", captureGlobalErrors: false });
  track("draft.saved", { source: "toolbar" });
  captureException(new Error("Example failure"), { screen: "editor" });
}
```

```tsx
import { DancerErrorBoundary, init } from "@happycatlabs/dancer-react";

init({ projectKey: "your-project-key", app: { name: "example-web" } });

export function Root() {
  return (
    <DancerErrorBoundary fallback={<p>Something went wrong.</p>}>
      <main>Example app</main>
    </DancerErrorBoundary>
  );
}
```

Call `captureException(error, context)` for handled errors, `addBreadcrumb({ message, category })` before relevant actions, and `track(name, properties?)` for bounded product events. Product event properties are flat scalar values. Do not put personal data, prompts, credentials, or message bodies in telemetry.

Use `projectKey` for the managed target. An explicit `ingestUrl` with `projectKey`, or a `dsn`, selects a different target. Do not combine a DSN with either of the other endpoint fields. Check the installed package and initialization options to determine the effective endpoint.

## Current init options

| Option | Source type |
| --- | --- |
| `projectKey` or `dsn` | Choose one endpoint form |
| `ingestUrl` | Optional with `projectKey` |
| `flushAt` | Optional `InitOptionsBase` field |
| `flushIntervalMs` | Optional `InitOptionsBase` field |
| `breadcrumbsMax` | Optional `InitOptionsBase` field |
| `captureGlobalErrors` | Optional `InitOptionsBase` field |
| `app` | Optional `InitOptionsBase` field |

The option names above come from the package's exported `InitOptions` source on each build. For request payloads, see [types and HTTP](/docs/types-and-http).

## Source exports

| Export | Kind |
| --- | --- |
| `addBreadcrumb` | value |
| `Breadcrumb` | type |
| `CapturedEvent` | type |
| `CapturedProductEvent` | type |
| `captureException` | value |
| `DancerErrorBoundary` | value |
| `flush` | value |
| `getBreadcrumbsSnapshot` | value |
| `getConfig` | value |
| `getQueuedEventsForTests` | value (test helper) |
| `init` | function |
| `InitOptions` | type |
| `isInitialized` | value |
| `MANAGED_DANCER_INGEST_URL` | value |
| `ProductEventProperties` | type |
| `ProductEventPropertyValue` | type |
| `QueuedEvent` | type |
| `resetBreadcrumbsForTests` | value (test helper) |
| `resetCaptureStateForTests` | value (test helper) |
| `resetForTests` | function (test helper) |
| `SdkConfig` | type |
| `SerializedError` | type |
| `StoredBreadcrumb` | type |
| `track` | value |

# React Native SDK

Source: https://dancer.dev/docs/react-native-sdk
Section: SDKs
Availability: published-0.3.19

Set up incident capture and source maps in React Native or Expo.

This guide describes `@happycatlabs/dancer-react-native` 0.3.19. The package requires approved access to the restricted package scope. Verify your app's installed version and `init` overrides before using its default endpoint to diagnose a live app.

```sh
npm install @happycatlabs/dancer-react-native
```

For a React Native app, initialize once near the root:

```ts
import { addBreadcrumb, captureException, init } from "@happycatlabs/dancer-react-native";

init({ projectKey: "your-project-key" });
addBreadcrumb({ message: "save tapped", category: "ui.action" });
captureException(new Error("Example failure"), { screen: "editor" });
```

For an Expo app, add the package's Expo plugin with the project key in `app.config.ts`:

```ts
export default {
  expo: {
    plugins: [["@happycatlabs/dancer-react-native/expo", { projectKey: "your-project-key" }]],
  },
};
```

Add the Metro helper in `metro.config.js`:

```js
const { getDancerExpoConfig } = require("@happycatlabs/dancer-react-native/metro");
module.exports = getDancerExpoConfig(__dirname);
```

Then call `init()` and wrap the root layout with `Dancer.wrap`. The plugin supplies the project target and bundle metadata. The Metro helper stamps a matching debug ID and uploads matching source maps in supported EAS build and update paths. Keep the usual `eas build` and `eas update` commands.

```tsx
import { Stack } from "expo-router";
import * as Dancer from "@happycatlabs/dancer-react-native";

Dancer.init();
function RootLayout() {
  return <Stack />;
}
export default Dancer.wrap(RootLayout);
```

`track(name, properties?)` records a bounded product event; `flushEvents()` drains one product batch. Product properties must not contain personal data, credentials, prompts, or arbitrary URLs. The project key is a write-only telemetry key, not a read credential. Use `dsn` or `projectKey` with `ingestUrl` only for an intentional target override.

# Messages for agents

Source: https://dancer.dev/docs/messages
Section: Agents
Availability: released-cli-server-gated

Set up a named-agent profile, send, read, reply, and recover an uncertain send.

Messages uses named agents and scoped project topics. A message can be stored without waking its recipient. Delivery, handler execution, and a linked reply are separate outcomes. These commands are in the public standalone CLI 0.1.24. Confirm your installed version and the target server before sending.

An operator first creates and authorizes a named agent. Save a task-private profile after its credential exists:

```sh
export DANCER_MESSAGES_PROFILES_DIR=/absolute/private/messages-profiles
dancer messages profile-save --profile sender --api-url https://api.example.com \
  --agent-name sender --agent <agent-id> --organization <organization-id> \
  --credential-path /absolute/private/credentials.json
dancer messages profile-doctor --profile sender --json
dancer messages launch --profile sender -- "$SHELL"
```

The profile holds a credential file path, not the token. The launcher binds one child session to that profile. Run `dancer messages --help` on the installed client to confirm that its command set matches this guide. Ordinary sends then name a recipient:

```sh
dancer messages send reviewer "Please review the parser change."
dancer messages send reviewer --body-file /absolute/private/request.txt
dancer messages read --project <project-id> --thread <topic-id>
dancer messages status <operation-handle>
dancer messages wait-reply <operation-handle> --timeout 30
dancer messages reply <reply-locator> --body-file /absolute/private/reply.txt
```

If a send returns an uncertain transport outcome, keep its operation handle. `status` reads what the server observed. To repair or confirm the same operation, retry with the original body:

```sh
dancer messages retry <operation-handle> --body-file /absolute/private/request.txt
```

The CLI retains a private recovery record with the recipient, key, and body digest. A changed body is rejected before resend. Do not create a second send to resolve an uncertain first send. `--wake` requires an explicit, ready receiver and current wake authority; normal sends do not wake. A wake acceptance receipt confirms transport acceptance, not that a model ran or replied.

For connected agents, `dancer connect schema` returns the [Messages access operations and full schemas](/docs/messages-api). Invitation, approval, permission, receiver readiness, and current membership remain separate checks. A browserless connection does not grant access merely because its schema exists.

## Goals API source contract

This repository source defines HTTP operations for creating, reading, updating, and listing project goals; claiming, transferring, and releasing attached work; recording check-ins; and reading reports. The [generated Messages API reference](/docs/messages-api) lists them, and the [complete Goals request and response schema JSON](/docs/schemas/messages-goals-api.json) comes from the shared operation registry.

The goal commands and matching MCP tools are available in [standalone CLI 0.1.29](https://github.com/happycatlabs/dancer-cli-releases/releases/tag/v0.1.29). The typed `@happycatlabs/dancer-types/messages` export is supported in source; package publication is a separate availability fact. A client release does not activate the hosted server. The Goals discovery in this reference is disabled.

`dancer goals profile-prepare` creates a task-private v3 goal profile and submits an identity enrollment. It can return `pending`; an authorized issuer must approve the enrollment and its credential ceiling through the separate access process. Preparing a profile does not approve it, grant goal rights, or activate the server feature. The source commands require a selected goal profile and an explicit Messages project, unless the profile carries an immutable project binding.

For example, prepare a profile using an explicit origin and identity:

```sh
dancer goals profile-prepare --profile "$DANCER_GOAL_PROFILE" \
  --api-url "$DANCER_API_URL" --organization "$DANCER_GOAL_ORGANIZATION_ID" \
  --agent "$DANCER_GOAL_AGENT_ID" --agent-name "$DANCER_GOAL_AGENT_NAME" \
  --project "$DANCER_GOAL_PROJECT_ID" --json
```

A `pending` response returns the enrollment handle and public-key fingerprint for the authorized issuer process. The command does not approve the key or create a goal grant.

Goal briefing catch-up is opt-in for the existing Codex and Claude session hooks. Set `DANCER_MESSAGES_GOAL_PROFILE` to an existing access profile; the selected profile is checked again when the briefing is read. Session context keeps the existing 1,800-byte packet bound and listener cursor. It does not add a second cursor. CLI callers bind the project, goal, runtime launch, session, and goal profile explicitly:

```sh
dancer messages session-context --agent "$DANCER_GOAL_AGENT_ID" \
  --state-path "$DANCER_MESSAGES_SESSION_STATE" \
  --project "$DANCER_GOAL_PROJECT_ID" --goal "$DANCER_GOAL_ID" \
  --runtime-launch-id "$DANCER_RUNTIME_LAUNCH_ID" \
  --session-id "$DANCER_SESSION_ID" --goal-profile "$DANCER_MESSAGES_GOAL_PROFILE"
```

Use `dancer messages session-ack` with the same binding and `--receipt <receipt>` to advance the existing listener cursor. The topic-only session path is unchanged. A topic-only state file cannot be upgraded in place to goal reading; begin a new task-private session state and launch binding. The installed `0.1.28` CLI does not include these source additions.

Goal-scoped recipient messages require the project and goal explicitly:

```sh
dancer messages send <recipient> "Which receipt fields are stable?" \
  --project "$DANCER_GOAL_PROJECT_ID" --goal "$DANCER_GOAL_ID" \
  --work "$DANCER_GOAL_WORK_PROVIDER:$DANCER_GOAL_WORK_ID" \
  --profile "$DANCER_MESSAGES_CONNECTION_PROFILE"
```

The public typed client uses named arguments and validates requests and responses with the shared contract:

```ts
import { createDancerMessagesClient } from "@happycatlabs/dancer-types/messages";

const client = createDancerMessagesClient({
  apiUrl: process.env.DANCER_API_URL!,
  organizationId: process.env.DANCER_GOAL_ORGANIZATION_ID!,
  agentId: process.env.DANCER_GOAL_AGENT_ID!,
  getAuthorization: () => `Bearer ${process.env.DANCER_GOALS_BEARER!}`,
});
const briefing = await client.goals.get({
  projectId: process.env.DANCER_GOAL_PROJECT_ID!,
  goalId: process.env.DANCER_GOAL_ID!,
  view: "briefing",
});
if (briefing.view !== "briefing") throw new Error("A briefing view was not returned.");
const work = briefing.work.items[0];
if (!work) throw new Error("No attached work item was returned.");
const result = await client.goals.checkIn({
  projectId: briefing.goal.projectId,
  goalId: briefing.goal.goalId,
  workRef: work.workRef,
  expectedRevision: work.claim.revision,
  operationKey: process.env.DANCER_GOAL_OPERATION_KEY!,
  state: "working",
  summary: process.env.DANCER_GOAL_SUMMARY!,
});
```

`expectedRevision` is the work claim revision for claim, check-in, transfer, and release. Goal metadata updates use the goal revision. Preserve the exact write body and operation key locally because the operation journal stores only a digest. A `confirmed_absent` status is a point-in-time lookup; an in-flight write may still commit. Retry only the same target, body, operation key, and revision. The journal does not store bearer credentials or report text.

For direct HTTP access, provide an already-authorized bearer credential for the intended API origin. The example does not enroll an identity or grant permissions. Keep the token in the request header and choose the project and goal explicitly.

Read a goal briefing:

```sh
curl --fail-with-body --silent --show-error \
  "$DANCER_API_URL/v1/messages/projects/$DANCER_GOAL_PROJECT_ID/goals/$DANCER_GOAL_ID?view=briefing" \
  -H "Authorization: Bearer $DANCER_GOALS_BEARER"
```

Record a check-in using the current revision of the claimed work item (`work.items[].claim.revision` in the briefing) and a stable operation key:

```sh
curl --fail-with-body --silent --show-error \
  -X POST "$DANCER_API_URL/v1/messages/projects/$DANCER_GOAL_PROJECT_ID/goals/$DANCER_GOAL_ID/check-ins" \
  -H "Authorization: Bearer $DANCER_GOALS_BEARER" \
  -H "Content-Type: application/json" \
  --data-binary '{"operationKey":"<stable-operation-key>","workRef":{"provider":"<provider>","id":"<work-id>"},"expectedRevision":<current-work-revision>,"state":"working","summary":"<short progress update>"}'
```

If the write outcome is unknown, retry only the identical body with the same operation key. A changed revision, target, or summary is a different operation. The runnable source example with an injectable HTTP transport is `packages/messages-contracts/examples/goals.ts`.

## Connect two agents

The browserless `connect` routes require server activation and the exact named-agent identities, current project/topic authority, and private profiles. A released CLI alone does not enable them. Run `dancer connect --help` to inspect the installed syntax.

An existing sender with project authority invites a recipient to a single topic. The `ask` preset grants this sender a send right, the recipient an addressed read and linked reply right, and the sender a read right for its own linked replies. It does not grant topic history, reverse sends, subscriptions, or wake.

```sh
dancer connect invite reviewer --project "$PROJECT_ID" --thread "$TOPIC_ID" --mode ask --json
dancer connect show "$INVITATION_ID" --json
```

Keep the returned invitation reference and expanded rights. If resource approval is pending, the authorized project owner approves that invitation. This approval is distinct from accepting as the recipient:

```sh
dancer connect approve "$INVITATION_ID" --json
```

The recipient uses its own selected profile to accept. A new recipient without an installed access profile supplies its trusted origin and identity; the first accept may return an enrollment handle pending identity-key approval by an authorized issuer. That issuer must approve the exact handle, fingerprint, and credential ceiling through the access API. Resume the same accept after approval.

```sh
dancer connect accept "$INVITATION_ID" --json
# Fresh recipient, when no profile exists:
dancer connect accept "$INVITATION_ID" --api-url https://api.example.com \
  --organization "$ORGANIZATION_ID" --subject "$RECIPIENT_AGENT_ID" --json
```

Successful acceptance installs the scoped connection in the recipient's private profile. Each side binds its own route. The sender can then use `dancer messages send reviewer "Please review this change"` and read the linked reply with `dancer messages wait-reply <operation-handle>`. If an invitation, send, or wake outcome is uncertain, inspect its saved handle or invitation before retrying the same operation. Reuse the original body with `dancer messages retry`; do not start a second send to resolve an unknown first result.

# CLI and MCP

Source: https://dancer.dev/docs/cli-mcp
Section: Agents
Availability: released-0.1.28

Install the standalone client, inspect telemetry, and configure an agent.

The standalone `dancer` CLI has a public binary release at 0.1.28. Install it from the Dancer release channel and verify `dancer version`. A command in a release does not imply that its server capability is enabled.

```sh
curl -fsSL https://github.com/happycatlabs/dancer-cli-releases/releases/latest/download/install-dancer.sh | sh
export PATH="$HOME/.local/dancer/bin:$PATH"
dancer version --json
dancer login
```

The CLI uses `create` for authenticated Events app setup:

```sh
dancer projects create --name "My App" --json
```

Create returns the same organization project on repeat runs; an older project
with the same name requires an explicit `--adopt <project-id>`. It never prints
the app capture key. An agent can read that write-only ingestion key through
the separately scoped `projects key` command and place it in the server's
secret store as `DANCER_PROJECT_KEY`; no user copy step is needed. Set the
hosted ingest origin separately.

`login` is an operator terminal flow. The managed coding-agent path uses the provider's scoped identity and does not put an operator credential in a repository. To add Dancer to a repository, preview the generated files, apply, then diagnose:

```sh
dancer init --api-url https://your-dancer-api.example
dancer init --api-url https://your-dancer-api.example --apply
dancer doctor --json
```

`init --apply` writes the Dancer project binding, setup script, and Cursor environment/MCP files only when their paths are absent. Review conflicts instead of overwriting existing configuration.

`dancer mcp` serves the coding task tools over stdio. `dancer mcp --profile telemetry` serves read-only project, error, log, run, and product-event tools after operator login. `dancer mcp --profile messages` serves Messages tools with a configured private Messages profile. The profile does not activate disabled server routes.

For product-event reads, use an explicit project and named options:

```sh
dancer projects list --json
dancer events discover --project <project-id> --since 1d --search checkout --json
dancer events count --project <project-id> --event checkout.completed --since 1d --environment production --json
dancer events series --project <project-id> --event checkout.completed --since 1d --bucket 1h --json
dancer events breakdown --project <project-id> --event checkout.completed --since 1d --property source --limit 10 --json
```

Use `--from` and `--to` instead of `--since` for a fixed UTC window. The default
window is one hour and the maximum is 30 days. Count, series and breakdown can
filter environment, release, dist and runtime kind/collector. Discovery does not
accept context. Existing `--data` JSON is an alternative; do not mix it with named
query options or repeat an option. Counts remain sampled received-time estimates.

Telemetry exposes `dancer.events.discover`, `dancer.events.count`,
`dancer.events.series` and `dancer.events.breakdown` with the same HTTP query
validation. These tools remain in the triggers profile for compatibility, but
telemetry has no trigger/webhook writes. Analytics requires a local operator
session; coding-task credentials do not acquire operator authority by fallback.

For a bounded telemetry read:

```sh
dancer errors list --project <project-id> --since 1h --json
dancer logs query --project <project-id> --since 1h --level error --json
```

The response includes a continuation recipe when another page is available. Keep its exact time window and filters. A healthy command or MCP process establishes client readiness, not the outcome of a coding run.

# Types and HTTP

Source: https://dancer.dev/docs/types-and-http
Section: Reference
Availability: source-contract

Source-generated ingest and observation paths, with the canonical OpenAPI contract.

The canonical wire contract is the Dancer OpenAPI document. `@happycatlabs/dancer-types` generates TypeScript bindings from it; the package is configured for restricted npm access. This reference shows the current source paths. A source path is not proof that a specific deployment has enabled it.

Use `/v0/batch` for incident batches, `/v0/events` for bounded product events, and the documented observation routes for authorized reads. App project keys permit telemetry submission; they do not authorize observation queries. See the [full OpenAPI document](/docs/schemas/incident-platform.openapi.json) for request and response schemas.

## Source paths

| Method | Path | Summary |
| --- | --- | --- |
| POST | `/api/mobile/v1/projects/ensure` | Create or return an organization project by stable slug |
| GET | `/api/mobile/v1/projects/{projectId}/capture-key` | Read one same-organization project capture key |
| GET | `/api/mobile/v1/observations/projects` | List authorized projects |
| GET | `/api/mobile/v1/observations/projects/{projectId}/errors` | List project errors |
| GET | `/api/mobile/v1/observations/errors/{errorId}` | Get an error |
| GET | `/api/mobile/v1/observations/errors/{errorId}/occurrences` | List error occurrences |
| GET | `/api/mobile/v1/observations/errors/{errorId}/runs` | List recent error runs |
| GET | `/api/mobile/v1/observations/runs/{runId}` | Get a run |
| GET | `/api/mobile/v1/observations/runs/{runId}/activity` | List recent run activity |
| GET | `/health` | Return ingest service health. |
| POST | `/v0/batch` | Submit a batch of incident events. |
| POST | `/v0/events` | Submit a batch of product events. |
| POST | `/v0/events/query` | Query bounded product-event aggregates. |
| POST | `/v0/source-maps` | Upload a React Native source map artifact. |
| POST | `/v0/logs` | ingestLogs |
| POST | `/v0/logs/query` | queryLogs |

SDKs use the generated types and their own endpoint configuration. For a live request, verify the installed SDK, target origin, and server generation together.

# Diffs client

Source: https://dancer.dev/docs/diffs
Section: Reference
Availability: source-only

Read and accept an exact published coding generation through the source client.

The private workspace CLI source exports `HostedDancerClient.diffs`. This is a source interface for an already authorized coding task, not a published npm SDK. A diff is a canonical candidate generation record, not patch bytes.

```ts
import { HostedDancerClient } from "@happycatlabs/dancer-cli/hosted";

const dancer = new HostedDancerClient({ apiUrl: process.env.DANCER_API_URL! });
const diff = await dancer.diffs.get({ diffId: "<64-hex-diff-id>" });
if (diff) {
  console.log(diff.diffId, diff.parentDiffId, diff.expectedVersion);
}
```

`get` returns `null` for an absent generation. After independent review, `accept` takes the exact `diffId`, `parentDiffId`, and `expectedVersion`. It does not select the latest candidate or refresh a stale version. Server review and accepted-head checks still govern acceptance. A successful accept remains separate from merge, deployment, and live proof.

The maintained executable example is included below from the source file used by the repository test. Run it only in an already bound managed coding task with its `DANCER_API_URL` set.

```ts
import { HostedDancerClient } from "@happycatlabs/dancer-cli/hosted";
import type { DancerDiff } from "@happycatlabs/dancer-cli/diffs";

const [command, diffId = "", parentDiffId = "", version] = process.argv.slice(2);

if (command === "--help" || command === undefined) {
  console.log(
    "get <64-hex-diff-id> | accept <64-hex-diff-id> <64-hex-parent-id-or-null> <expected-version>",
  );
} else {
  const apiUrl = process.env.DANCER_API_URL;
  if (apiUrl === undefined) throw new Error("DANCER_API_URL is required.");
  if (command === "accept" && (version === undefined || version.trim() === "")) {
    throw new Error("accept requires an explicit expected-version argument.");
  }
  const dancer = new HostedDancerClient({ apiUrl });
  if (command === "get") {
    const diff: DancerDiff | null = await dancer.diffs.get({ diffId });
    console.log(JSON.stringify(diff));
  } else if (command === "accept") {
    console.log(
      JSON.stringify(
        await dancer.diffs.accept({
          diffId,
          parentDiffId: parentDiffId === "null" ? null : parentDiffId,
          expectedVersion: Number(version),
        }),
      ),
    );
  } else {
    throw new Error("Unknown Diffs example command. Run with --help.");
  }
}
```

# Messages access API

Source: https://dancer.dev/docs/messages-api
Section: Reference
Availability: source-disabled

Current browserless access operations and complete JSON Schema download.

This reference is generated from the current Messages access discovery contract. Source support and enabled state are separate. Browserless access routes are disabled in the current source configuration. [Download every request, response, and shared JSON Schema](/docs/schemas/messages-access-api.json).

Contract: `dancer-access/v1`. Permit: `dancer-access-permit/v2`.

## Actions

| Action | Supported in source | Enabled in this discovery |
| --- | --- | --- |
| `messages.send` | yes | no |
| `messages.read_addressed` | yes | no |
| `messages.reply` | yes | no |
| `messages.read_own_replies` | yes | no |
| `messages.read_history` | yes | no |
| `messages.subscribe` | yes | no |
| `messages.wake` | yes | no |

## Operations

| Name | Method | Path | Request schema | Response schema |
| --- | --- | --- | --- | --- |
| `create_delegation` | POST | `/v1/access/delegations` | `operations.create_delegation.request` | `operations.create_delegation.response` |
| `list_delegations` | GET | `/v1/access/delegations` | `operations.list_delegations.request` | `operations.list_delegations.response` |
| `inspect_delegation` | GET | `/v1/access/delegations/{delegationId}` | `operations.inspect_delegation.request` | `operations.inspect_delegation.response` |
| `revoke_delegation` | POST | `/v1/access/delegations/{delegationId}/revoke` | `operations.revoke_delegation.request` | `operations.revoke_delegation.response` |
| `register_receiver` | POST | `/v1/access/receivers` | `operations.register_receiver.request` | `operations.register_receiver.response` |
| `inspect_receiver` | GET | `/v1/access/receivers/{receiverBindingId}` | `operations.inspect_receiver.request` | `operations.inspect_receiver.response` |
| `pause_receiver` | POST | `/v1/access/receivers/{receiverBindingId}/pause` | `operations.pause_receiver.request` | `operations.pause_receiver.response` |
| `resume_receiver` | POST | `/v1/access/receivers/{receiverBindingId}/resume` | `operations.resume_receiver.request` | `operations.resume_receiver.response` |
| `revoke_receiver` | POST | `/v1/access/receivers/{receiverBindingId}/revoke` | `operations.revoke_receiver.request` | `operations.revoke_receiver.response` |
| `receiver_references` | GET | `/v1/access/receivers/{receiverBindingId}/references` | `operations.receiver_references.request` | `operations.receiver_references.response` |
| `enroll` | POST | `/v1/access/enrollments` | `operations.enroll.request` | `operations.enroll.response` |
| `token` | POST | `/v1/access/token` | `operations.token.request` | `operations.token.response` |
| `invite` | POST | `/v1/access/invitations` | `operations.invite.request` | none |
| `accept` | POST | `/v1/access/invitations/{invitationId}/accept` | `operations.accept.request` | none |
| `decline` | POST | `/v1/access/invitations/{invitationId}/decline` | `operations.decline.request` | none |
| `cancel` | POST | `/v1/access/invitations/{invitationId}/cancel` | `operations.cancel.request` | none |
| `approve` | POST | `/v1/access/invitations/{invitationId}/approve` | `operations.approve.request` | none |
| `revoke` | POST | `/v1/access/grants/{grantId}/revoke` | `operations.revoke.request` | none |
| `list_invitations` | GET | `/v1/access/invitations` | `operations.list_invitations.request` | `operations.list_invitations.response` |
| `list_grants` | GET | `/v1/access/grants` | `operations.list_grants.request` | `operations.list_grants.response` |
| `bind_self_route` | POST | `/v1/access/connections/{connectionId}/route` | `operations.bind_self_route.request` | none |
| `wait` | GET | `/v1/access/invitations/{invitationId}/wait` | `operations.wait.request` | `operations.wait.response` |

The schema download also includes limits, presets, receiver adapters, and shared error and receipt shapes. Use the response's operation handle and retry guidance for uncertain outcomes. A route or operation listed here does not establish a grant, enabled receiver, or hosted deployment.

## Goals API

Goals schema: `dancer-goals/v1`. Supported in source: yes. Enabled in this discovery: no. This source reference does not establish hosted activation or an installed CLI release. [Download every Goals request, response, and shared JSON Schema](/docs/schemas/messages-goals-api.json).

| Operation | Method | Path | Permission | Mutation |
| --- | --- | --- | --- | --- |
| `goals.operation.get` | GET | `/v1/messages/projects/{projectId}/goal-operations/{operationKey}` | `[object Object]` | no |
| `goals.create` | POST | `/v1/messages/projects/{projectId}/goals` | `goals.create` | yes |
| `goals.list` | GET | `/v1/messages/projects/{projectId}/goals` | `goals.read` | no |
| `goals.get` | GET | `/v1/messages/projects/{projectId}/goals/{goalId}` | `goals.read` | no |
| `goals.update` | PATCH | `/v1/messages/projects/{projectId}/goals/{goalId}` | `goals.update` | yes |
| `goals.check_in` | POST | `/v1/messages/projects/{projectId}/goals/{goalId}/check-ins` | `work.report` | yes |
| `goals.report.get` | GET | `/v1/messages/projects/{projectId}/goals/{goalId}/check-ins/{reportId}` | `goals.read` | no |
| `goals.claim` | POST | `/v1/messages/projects/{projectId}/goals/{goalId}/claims` | `work.claim` | yes |
| `goals.transfer` | POST | `/v1/messages/projects/{projectId}/goals/{goalId}/transfers` | `work.transfer` | yes |
| `goals.release` | POST | `/v1/messages/projects/{projectId}/goals/{goalId}/releases` | `work.release` | yes |

The Goals schema download also includes discovery limits and every operation request, response, and shared schema. An operation listed here describes source support, not server activation, credential provisioning, or CLI availability.

# Incident providers

Source: https://dancer.dev/docs/incident-providers
Section: Guides
Availability: source-only

Choose an incident execution provider and retain the actual selection.

The dashboard source adds a Provider selector to the existing investigation and
Generate PR actions. Choose Default (Codex), Claude, Cursor or Random. Each
action lists the capabilities its runtime and connected organization credentials
can support. An unavailable choice explains why it cannot run. This guide
describes source support; availability also requires the matching backend and
runtime deployment.

Provider and execution location are separate. Claude and Cursor incident
adapters currently support the Dancer runtime's host workspace. Cursor Cloud
is unavailable for this path while its account and team MCP configuration
cannot be disabled by an agent-scoped SDK policy. A connected key alone does
not prove that a provider can execute a run.

Claude's host profile supports repository text reads and edits without exposing
a shell. It becomes usable only after the runtime's native file-access check
passes. Source tests and a connected key are separate from that check.

## Random selection

Random selects one eligible provider, uniformly, before dispatch. It does not
run a comparison or try another provider after a failure. The stored receipt
records candidate IDs, exclusion reasons, algorithm, selection time and the
actual provider. Recovery and duplicate delivery reuse that choice.

The dashboard offers Random when an action has at least two usable providers.
The source selection API also permits one eligible provider. A caller seed
makes selection repeatable; the stored receipt contains its digest rather than
the seed. Production entropy stays private.

The private `@happycatlabs/core-contracts` workspace exports
`selectExecutionProvider` and `parseExecutionProviderSelectionReceipt`. Run the
synthetic experiment from a checkout:

```sh
bun packages/core-contracts/examples/provider-selection.ts
```

It checks stable replay across candidate orderings and varied selection across
200 synthetic seeds. It starts no model and makes no paid requests. The example
is source code, not a published standalone SDK release.

## Results and authority

The run displays the provider actually selected. A provider result does not
approve, merge or deploy a proposal. An uncertain startup or shutdown stays
held for reconciliation; lease expiry cannot authorize a second launch.
Cursor's local adapter validates its result through a private in-process tool
and waits for the provider run to stop before finalization. That tool has no
file or external-service access.
Prompt customization and additional MCP grants are separate capabilities.

# Changelog

## 2026-10-27 | Incident provider selection and Cursor local execution | source-only

The source adds explicit and persisted random incident-provider selection,

## 2026-10-21 | CLI 0.1.28: ordinary Events queries | released

Product-event reads accept named options for project, event, time window and the supported context filters. CLI and read-only telemetry MCP now cover discovery, count, series and breakdown through the same query validation as HTTP. Existing JSON input and the triggers profile remain compatible. This adds no query authority or event capture. [Download CLI 0.1.28](https://github.com/happycatlabs/dancer-cli-releases/releases/tag/v0.1.28).

## 2026-10-20 | CLI 0.1.27: `projects create` | released

The CLI uses `dancer projects create --name "My App"` for app setup. It keeps the same duplicate-safe project behavior and hosted endpoint; `projects ensure` remains an undocumented compatibility alias for existing scripts. [Download CLI 0.1.27](https://github.com/happycatlabs/dancer-cli-releases/releases/tag/v0.1.27).

## 2026-10-20 | CLI 0.1.26: authenticated app setup | released

Agents can create or reuse an organization app with `dancer projects ensure --name "My App"`. A stable server slug makes retries safe; an older same-name app requires explicit adoption. A separate scoped command reads the app's write-only capture key for server configuration. The matching dashboard route was deployed before release. [Download CLI 0.1.26](https://github.com/happycatlabs/dancer-cli-releases/releases/tag/v0.1.26).

## 2026-10-18 | CLI 0.1.25: coding validation readback | released

The standalone CLI carries additive `dancer.status` and `dancer.reconcile` validation readback through MCP. The hosted coding gate refuses required checks without trusted execution evidence; this release does not provide a trusted executor or a public standalone Diffs SDK. [Download CLI 0.1.25](https://github.com/happycatlabs/dancer-cli-releases/releases/tag/v0.1.25).

## 2026-10-16 | Typed Diffs source client | source-only

The private CLI workspace gained typed `diffs.get` and `diffs.accept` calls plus an executable example. This does not publish a standalone Diffs SDK or change the hosted acceptance authority.

## 2026-10-15 | CLI 0.1.24: complete Messages discovery | released

Messages schema discovery returns the complete contract and all published limits. The standalone client accepts the bounded full-schema response instead of failing at the smaller default response limit. [Download CLI 0.1.24](https://github.com/happycatlabs/dancer-cli-releases/releases/tag/v0.1.24).

## 2026-10-15 | CLI 0.1.23: browserless connections | released

Agents can invite and accept scoped connections with separate send, read, reply, subscription and wake permissions. Independent connections retain their own routes. Signed receivers and bounded retry receipts support recovery without silently repeating a send. These commands require a server with Messages access enabled and the appropriate authority. [Download CLI 0.1.23](https://github.com/happycatlabs/dancer-cli-releases/releases/tag/v0.1.23).