Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chartcastr.com/llms.txt

Use this file to discover all available pages before exploring further.

A snapshot is a frozen, multi-page PDF render of your briefing at a point in time, plus the act of delivering it to your destination. Snapshots are throttled to once per calendar month per briefing.

​
When snapshots run

TriggerSourceThrottle?
ScheduledThe monthly cron, fired by the briefing’s connection at the day-of-month + time you configured.Yes.
Manual (“Send Snapshot”)The button in the composer or list page.Yes.
Manual overrideOrg admins only — bypasses the monthly throttle for support / failed-delivery retries.No.
If a scheduled or manual run hits the throttle, the orchestrator writes a BriefingContent with status = UNCHANGED and runWarnings = [{ code: 'THROTTLED_MONTHLY' }], then exits without calling the AI or rendering a PDF.
”Calendar month” is computed in your organisation’s timezone, not UTC. A briefing scheduled for the 1st of the month will fire on your local 1st, and lastSnapshotAt is compared against the start of that local month.

​
Schedule shape

The briefing settings page exposes a structured form, not a cron textarea:
  • Day of month: 1–28 (avoids the 29/30/31 edge cases).
  • Hour: 0–23, in your org timezone.
  • Minute: 0–59.
The server materialises this to a cron expression internally — the UI never sees one.

​
What’s in the PDF

The PDF is rendered server-side with @react-pdf/renderer (Bun-compatible, no headless browser). Layout:
PageContents
1 — CoverBriefing name, period label (e.g. “April 2026”), generated timestamp, organisation name, description, brand mark.
2 — Big PictureThe overall review — aiSummaryLong body + highlight bullets. Placed up-front.
3+ — Per-row sectionsFor each row: title, item grid (chart image + name + short summary, 2 per row), then the cross-analysis commentary + highlights.
Last — AppendixPer-item full long summaries (anything that didn’t fit above), and a data-freshness table showing each item’s latest.generatedAt vs. fresh / stale.
The PDF is uploaded to R2 and linked from BriefingContent.pdfUrl so it can be re-downloaded from the snapshot history page even after delivery.

​
Delivery

Briefings are delivered to your configured destination. The cover message includes the briefing name, period label, the overall short summary, and a link to view the snapshot online. The PDF is attached to the message wherever the destination supports attachments; if the file is too large for the destination, Chartcastr falls back to a download link instead. The deliverable is consistent across destinations — only the wrapping format differs.

​
Snapshot history

Every run — successful, throttled, failed — writes a BriefingContent row. The /admin/briefings/[id]/snapshots page lists them, ordered newest-first. By default the list filters to status = SUCCESS and pdfUrl IS NOT NULL; toggle to show all. Each row records:
  • Completion date, status, trigger type (Scheduled / Manual)
  • Token usage breakdown (titles + rows + overall)
  • PDF download link
  • A view of the frozen briefingSnapshot so the snapshot detail page can re-render the briefing exactly as it was delivered, even if you’ve since changed the live composition.

​
Failure modes

CodeCauseWhat it means
THROTTLED_MONTHLYA run for the same briefing already completed this calendar month.Run exits early. No AI, no PDF. Use the admin override to bypass.
BRIEFING_COMMIT_IN_PROGRESSA save is already in flight.Wait for the in-flight run to finish.
PLAN_UPGRADE_REQUIREDThe org’s plan dropped below paid.Read access still works; mutations and new snapshots are blocked. Existing scheduled connections move to DEGRADED.
A run is SUCCESS when at least one row produced commentary AND the overall summary call succeeded. A row that failed individually is recorded with aiError set and surfaces on the snapshot detail page as a per-row “retry” affordance — it does not block the rest of the briefing from being delivered.