# CARBON private Feedback Service

This is the optional self-hosted queue and reviewer surface used by
`/carbon-feedback`. It is not a testers.ai cloud service and it has no public
fallback. CARBON’s local Feedback workspace works without this service.

## Deploy privately

1. Copy `docker-compose.yml` to your private environment and set:
   - `CARBON_FEEDBACK_PUBLIC_URL` to the private HTTPS URL reviewers can reach;
   - `CARBON_FEEDBACK_TOKEN_SECRET` to a random value of at least 32 characters;
   - `CARBON_FEEDBACK_API_KEYS` to one or more comma-separated client keys.
2. Keep the service behind your approved private network, reverse proxy, or
   identity gateway. The capability URL is still secret; do not forward it.
3. Start it with `docker compose up -d --build`.
4. To send rich email invitations, configure either `SMTP_URL` plus
   `CARBON_FEEDBACK_MAIL_FROM`, or `CARBON_FEEDBACK_MAIL_WEBHOOK_URL` for your
   approved internal mail gateway. With neither configured, reviews remain
   queued and the owner receives the reviewer capability URL instead.

The server stores only HMAC hashes of reviewer capabilities in its state file.
It does not fetch artifacts, browser sessions, repositories, cookies, or
credentials. Local file paths are shown as text; to let a remote reviewer see
an artifact, supply an intentionally shared private URL or upload it through
your own approved system.

## CARBON invocation

Use `/carbon-feedback` with an artifact and focus. To dispatch an invitation,
explicitly provide the configured `privateServiceUrl`, a one-time
`privateServiceKey`, recipient email, and `privateServiceConfirmed=true` after
reviewing the scope. The key is not written to `.carbon` state or reports.

Rich HTML mail contains a button to the responsive private feedback page.
Embedded forms in email are intentionally not used because mainstream clients
strip forms and scripts or make them unsafe.

When the reviewer responds, the project owner runs CARBON Feedback `sync` with
the same explicitly confirmed service URL and one-time service key. The service
returns only the response DTO for that specific review; CARBON stores it in the
project-local request and refreshes the report. A queued invitation is never
reported as received feedback.
