README.md

# trace

Private incident notebook, Git fix-candidate inbox, deployment-receipt evidence store, and reviewed Astro Markdown exporter for goonk's `/failures` page.

```bash
cp .env.example .env
npm start
```

Node 24+, no runtime dependencies. Uses built-in `node:sqlite`. Set `TRACE_PASSWORD`. Incidents remain private until a human explicitly publishes them. Published projections are available through `GET /api/v1/public/failures`, `GET /api/v1/public/failures/:slug`, and `GET /api/v1/public/failures/:slug.md` for runtime and build-time consumers.

Git candidate scanning is optional and disabled by default. If an installation deliberately mounts read-only repository mirrors, list their container paths in `TRACE_REPOS`; production receipt ingestion does not require repository access.

Production can scan repositories without Git checkouts through Gitea's read-only API. Set `TRACE_GITEA_URL` and a comma-separated `TRACE_GITEA_REPOS` list such as `explewd/flit`. Public repositories require no token; `TRACE_GITEA_TOKEN` is optional for private repositories. A failed repository is skipped rather than failing the inbox.

Producer onboarding, shared-runner examples, deployment-host responsibilities, and verification are documented in [`docs/INTEGRATING_PROJECTS.md`](docs/INTEGRATING_PROJECTS.md).

## Deployment receipts v1

`POST /api/v1/events` accepts versioned build/deployment receipts using a project-scoped bearer token configured as `TRACE_RECEIPT_TOKENS=goonk:token,retur:other-token`. Event IDs are idempotent. `GET /api/v1/public/projects/:project/latest` returns an explicit allowlisted projection; raw payloads remain private.
Build private incident notebook MVP 2026-07-20 20:25:17 +02:00			`# trace`

			Private incident notebook, Git fix-candidate inbox, deployment-receipt evidence store, and reviewed Astro Markdown exporter for goonk's `/failures` page.

			```bash
			`cp .env.example .env`
			`npm start`
			```

Serve published failure details as JSON 2026-07-21 02:39:24 +02:00			Node 24+, no runtime dependencies. Uses built-in `node:sqlite`. Set `TRACE_PASSWORD`. Incidents remain private until a human explicitly publishes them. Published projections are available through `GET /api/v1/public/failures`, `GET /api/v1/public/failures/:slug`, and `GET /api/v1/public/failures/:slug.md` for runtime and build-time consumers.
Make Git repository scanning opt-in 2026-07-20 21:09:04 +02:00
			Git candidate scanning is optional and disabled by default. If an installation deliberately mounts read-only repository mirrors, list their container paths in `TRACE_REPOS`; production receipt ingestion does not require repository access.
Add versioned deployment receipt ingestion 2026-07-20 21:01:52 +02:00
Scan public repositories through Gitea API 2026-07-20 22:19:44 +02:00			Production can scan repositories without Git checkouts through Gitea's read-only API. Set `TRACE_GITEA_URL` and a comma-separated `TRACE_GITEA_REPOS` list such as `explewd/flit`. Public repositories require no token; `TRACE_GITEA_TOKEN` is optional for private repositories. A failed repository is skipped rather than failing the inbox.

Document cross-project receipt integration 2026-07-20 22:03:37 +02:00			Producer onboarding, shared-runner examples, deployment-host responsibilities, and verification are documented in [`docs/INTEGRATING_PROJECTS.md`](docs/INTEGRATING_PROJECTS.md).

Add versioned deployment receipt ingestion 2026-07-20 21:01:52 +02:00			`## Deployment receipts v1`

			`POST /api/v1/events` accepts versioned build/deployment receipts using a project-scoped bearer token configured as `TRACE_RECEIPT_TOKENS=goonk:token,retur:other-token`. Event IDs are idempotent. `GET /api/v1/public/projects/:project/latest` returns an explicit allowlisted projection; raw payloads remain private.