Seers, content from outside signals
Watch a GitHub repo, a Notion workspace, a spec, or the news, and turn what changes into headlines, drafts, or just events your own pipeline reads.
A seer watches something outside Letterstory and reacts when it changes. It is a standing instruction: watch this source, since where you left off, and tell me what's new and relevant. Primitives → Seers in the header (or its own tab, if you pinned it) has two tabs: Seers (the watchers) and Headlines (what they've produced, including held drafts).
One poll is one run: scan the source since the seer's last position, dedupe against what it has already seen, judge each item for relevance, record it, and (unless you say otherwise) produce something from it.
Create one
Press New seer and pick a signal:
Internal signals: GitHub · PR merged, GitHub · New release, Notion · New messaging, Spec change (a URL whose content you want watched).
External signals: News & trends (a query), Laws & regulations (a query).
Then configure it:
| Setting | Options |
|---|---|
| Name | Anything |
| When it fires | Suggest only, create a headline suggestion for you to queue. Auto, create a draft and start Auto-Pen immediately. |
| Draft which items? | Everything from this source or Only items that match my positioning |
| Destination collection | Where drafts go |
| Output template | Default (the collection's template, or classic prose), one of your templates, or None · classic prose (KB-208) |
| Writing kernel | Auto · recommended, Inherit org kernel, or a specific voice (under Show advanced) |
| Mention your company | Woven in naturally, A subtle nod, or No mention (under Show advanced) |
| Poll cadence | How often to check (under Show advanced) |
The dialog keeps any setting it doesn't manage, so a seer configured over the API keeps its API-only settings when someone renames it in the app.
Connections
GitHub and Notion seers need a connection. For GitHub, a token unlocks private repositories. For Notion, create an internal integration at notion.so/my-integrations, share the pages the seer should see with it, and paste its secret; a Notion integration only sees pages explicitly shared with it. The Seers page shows connection status.
What it judges against
A seer scores relevance against your organization's positioning: priority topics, stances, avoid-topics, your description, your identity. You can override any of that on the seer itself (config.relevance over the API), field by field. A field you declare wins; a field you leave out inherits the organization at run time, freshly each run. That is how you stand up a seer watching a subject your positioning doesn't cover, without rewriting the positioning for everything else.
Creating a seer no longer writes anything to your organization's positioning on your behalf.
Reading what a seer found
Open a seer to see its events: what it detected, duplicates it merged, and whether each was judged relevant. Dismiss events you don't want acted on. In Suggest only mode, its headlines appear on the Headlines tab; queue them into a collection from there.
Held drafts
In Auto mode a seer's draft can be held if its facts couldn't be confirmed against the source. Headlines → Held for review lists them with the reason; release or discard (KB-306).
Running one yourself
run_seer polls a seer now instead of waiting for the schedule, and takes three options:
| Option | What it does |
|---|---|
dry_run: true | Scan and judge, persist nothing at all: no events, no cursor move, nothing produced. Returns the signals it would have recorded with their verdicts. Test a query before it floods a collection. |
produce: false | Detect and record events only. Nothing becomes a headline or a draft; your own pipeline reads list_seer_events and decides. |
async: true | Queue the run and return a run id to poll with get_seer_run. A news or regulation scan is a multi-minute web search, so prefer this over waiting on the call. |
letterstory seers run <seer-id> --dry-run
letterstory seers run <seer-id> --async
letterstory seers run-status <run-id>
Every run keeps a record: what it ran with (the source scanned, the positioning the judge used and which of it you declared), what it found, and a verification read-back of five checks: sourced, judged, deduped, cursor_advanced, produced. A failed poll reads back as five skippeds rather than five things that were checked. A provider outage is reported as a failure with the reason, never as "found nothing".
Watching without a destination
Over the API a seer can be created with no destination collection at all. It scans, dedupes and judges forever, and never produces: produce is forced off whatever a run asks for. That is the shape to use when the output belongs in your own CMS, your own pipeline, or your own notifications, and you want none of Letterstory's content concepts involved. Auto mode is refused without a collection, since a draft needs somewhere to go. The dialog in the app always asks for a collection; this one is API-only.
What a run costs
Your organization gets 50 seer runs on the house. Only runs you ask for directly count: run_seer, a dry run, and the app's run-now button. The scheduled heartbeat polling your seers on their standing instruction is recorded but not billed, which is why turning this on changed nothing for seers already running. A scan that fails outright is free. get_seer_run_balance (CLI seers balance) shows granted, used and available.
A dry run costs a run: the web search happens either way.
Reproducible setup
letterstory seers export --file seers.json writes every seer as a manifest; seers apply --file seers.json upserts from one, by name, never deleting. Handy for setting up a second workspace the same way.