📄 Reports
Research outputs with rich HTML content. The knowledge base of the system.
What It Does
The Reports page is a registry of research documents. Each report is a hybrid entity: D1 stores the metadata
(title, status, tags) while the actual content lives as static HTML in portal/public/reports/.
Reports are the primary output of research jobs.
Report Lifecycle
Tab Views
| Tab | Shows |
|---|---|
| Active | Reports with status active — current, relevant research |
| Backlog | Reports queued for review or follow-up |
| Archive | Completed or outdated reports (soft-deleted via status change) |
Report Features
| Feature | Description |
|---|---|
| Rich HTML content | Reports can contain any HTML — tables, charts, code blocks, diagrams. Rendered in an iframe or via direct link |
| Two modes | Article (long-form research) and Slide deck (presentation-style, multiple pages) |
| Feedback | Leave actionable feedback on a report. Clara picks it up on sweep |
| Comments | Permanent audit trail — add notes, corrections, follow-up questions |
| Direct link | Each report is accessible at /reports/{slug}/ — shareable, no login required |
Creating Reports
Via Inbox (Automated)
Select Research mode in Inbox Compose, describe the research topic, submit. Bifrost creates the HTML and registers it in D1.
Via Agent Session (Manual)
During a copilot session, the agent can write HTML to portal/public/reports/{slug}/index.html
and POST metadata to /api/reports. Deploy with wrangler pages deploy.
wrangler pages deploy to become
accessible. D1 metadata is available immediately, but the HTML content needs a deploy.
Report Structure
Each report lives in portal/public/reports/{slug}/ and contains:
| File | Purpose | URL |
|---|---|---|
index.html |
The rendered HTML report — self-contained with inline CSS, dark theme, back-links | /reports/{slug}/ |
report.md |
Agent-readable markdown source. Lower token cost for AI consumption — agents should read this, not the HTML | /reports/{slug}/report.md |
context.md |
Research provenance — captures the original request, discussion points, sources consulted, and generation metadata (job ID, session ID, timestamps, model used) | /reports/{slug}/context.md |
context.md Format
The context.md file captures traceability metadata so you can trace any report back to its
origin:
# Context: {Report Title}
## Request
{The original user request or trigger}
## Discussion
{Key discussion points, decisions made}
## Sources Consulted
- {URLs, files, APIs read}
## Generated
- Date: YYYY-MM-DD HH:MM
- Job ID: {Bifrost job ID}
- Session ID: {CLI session ID}
- Backend: {claude/gemini} / {model}
- Requested by: {portal/copilot/bifrost}
context.md is only omitted for standalone reports with no
traceable origin (e.g., manually authored analysis).
For Agents
GET /api/reports — list all reports.
POST /api/reports — register new report metadata.
PATCH /api/reports — update status/tags.
See Report entity for full schema.