BitterLog

BitterLog is an append-only evidence workbench for agent-run proof: raw traces, receipts, prompt/output artifacts, annotations, stable digests, and account-scoped retrieval.

It is built for AI-native operators who need to preserve what happened during agent work, recover the exact source record behind a summary or failure, and make evidence inspectable for later review.

Place In Bitter

Bitter is an agent-operable software environment. It gives AI agents persistent workspaces where repositories, credentials, hosting, email, tests, deploys, logs, checks, and work history are connected.

BitterLog owns the evidence and memory part of that environment:

• raw agent traces, run receipts, prompt/output artifacts, and annotations stay tied to stable digests and timestamps
• operators can move from a summary back to the exact stored source record
• Bitter account authority scopes access without creating a BitterLog-only account system
• analytics and similarity are projected read models, not the ledger itself

BitterLog is not Factory's control plane, BitterGrid's deployment executor, BitterPass's credential authority, a generic observability dashboard, or a source of private customer runbooks.

Product Model

The public product loop is:

Agent Run -> Raw Event or Bucket Object -> Digest/Timestamp/Receipt -> Annotation/Query -> Reviewable Proof

The public site can claim append-only evidence, raw trace preservation, digests, timestamps, annotations, account-scoped access, and API-indexed retrieval paths. Claims about customer-facing raw SQL, live ClickHouse search, similarity, buyer access, or form forwarding require current live proof before they are stated as available.

Current public status:

• the public marketing surface is live at bitterlog.com
• the API index is live at api.bitterlog.com/api/v1
• the public API status reports ledger counts and analytics.enabled: false
• access routes through Bitter account surfaces
• onboarding remains request-reviewed during launch
• the marketing site does not expose a working form-forwarding endpoint

Repository Role

This repository contains the public BitterLog marketing site at bitterlog.com. It is safe to index and should remain useful as public source context for the product, the deployment boundary, and the live verification loop.

This repository owns:

• the public marketing home page
• public product copy and metadata
• static Nuxt generation
• Radicchio deployment manifest and manual deploy helper
• public crawler and AI-readable files
• Markdown alternate content for the public home page
• the /up/ release identity payload
• public smoke tests and static-header expectations

It does not own the BitterLog API implementation, customer evidence payloads, credential material, account delegation internals, ClickHouse bootstrap, private analytics operations, private support/debug material, or Factory operator runbooks. Those surfaces live outside this public marketing repository.

Links

• BitterLog website: bitterlog.com
• Public source: sheetgenius/bitterlog-marketing
• API index: api.bitterlog.com/api/v1
• API status: api.bitterlog.com/api/v1/status
• Health/release identity: bitterlog.com/up
• Markdown page mirror: index.md
• AI crawler entry points: llms.txt, llms-full.txt
• Public change history: CHANGELOG.md
• Contribution guide: CONTRIBUTING.md
• Security and public boundary: SECURITY.md
• Bitter: bitter.sh
• BitterGrid: bittergrid.com

Deployment

BitterLog's public marketing site is deployed on BitterGrid as the bitterlog.com service and served as a Radicchio/static site.

Current deployment truth:

• service key: bitterlog.com
• GitHub source: sheetgenius/bitterlog-marketing
• release identity: verify https://bitterlog.com/up/ against the intended source commit after each deploy
• source freshness: verify with bitter grid services source check bitterlog.com
• health path: /up/
• live health URL: https://bitterlog.com/up/
• deploy path: GitHub source event -> BitterGrid build/deploy -> Radicchio/static site
• Radicchio site id: 92
• Radicchio hostname: bitterlog.com

Known deployment caveats:

• Scripts/deploy is a manual Radicchio fallback and requires RADICCHIO_API_TOKEN; it is not the observed current source-event deploy trigger
• Radicchio serves the current edge security header baseline directly: X-Frame-Options: SAMEORIGIN and Permissions-Policy: camera=(), microphone=(), geolocation=()
• Radicchio currently serves Markdown files as static files and may not emit canonical HTTP Link headers from repo-local _headers

Development

bun install --frozen-lockfile
bun run generate
bun run qa:smoke
bun run test:headers

Useful commands:

• bun run generate - writes static output to .output/public.
• bun run qa:smoke - runs the Playwright public-site smoke test.
• bun run test:headers - checks the checked-in Radicchio edge header baseline.
• Scripts/radicchio plan - shows the deployable static file payload.
• Scripts/workcell-prepare - validates and generates the source artifact.
• Scripts/workcell-verify - verifies the live public routes and release identity.

Do not start a development server unless the human asks for it. The smoke test starts its own local static server when no PLAYWRIGHT_BASE_URL is supplied.

Public Context

This repository is public after source shape, live verification, and public-source hygiene passed. README text, page copy, metadata, sitemap entries, Markdown alternates, and public links should preserve durable context for humans, search engines, and AI systems that index public repositories. Keep the live source link aligned with the actual GitHub repository visibility.

When a page claim changes, update the matching Markdown twin, public/llms.txt, public/llms-full.txt, metadata, sitemap, smoke tests, and changelog in the same change.