/radar

name: radar
description: "When you want to monitor known sources on a schedule and feed the good stuff into your second brain. Configure sources once (YouTube, RSS/newsletters, subreddits, Hacker News, Bluesky, Mastodon, X, LinkedIn, keyword searches); each run fetches only what's new, scores it against your stated focus, writes one digest to the vault, and auto-captures high-signal items into raw/. Everything else waits in the digest until you promote it. Modes — run, digest, promote, add / sources / pause, doctor, schedule (daily launchd or systemd job). Triggers on \"/radar,\" \"run my radar,\" \"check my sources,\" \"what's new from my sources,\" \"add a source,\" \"monitor this channel,\" \"watch this subreddit,\" \"track this account,\" \"daily digest,\" \"promote item 4,\" \"radar doctor.\" Complements second-brain (radar fills raw/, second-brain compiles it) and deep-research (standing surveillance vs a one-off dive)."
metadata:
  version: 0.4.0

/radar — Standing surveillance on the sources you care about

`deep-research` answers a question you asked. `radar` surfaces the answers to questions you haven't asked yet, from sources you already trust, every day, without you going to look.

Mental model

sources.yaml  →  fetch new only  →  score  →  digest  →  promote  →  raw/  →  /sb compile
  (config)        (state files)     (1–5)    (vault)    (you)      (vault)     (wiki)

Two hard rules keep this from becoming noise:

1. **Only one thing is written per run by default** — the digest. Individual `raw/` captures happen only for items that clear the auto-capture bar, or that you explicitly promote. 2. **Nothing is fetched twice.** Every source has a state file of seen item IDs. A run at 7am and a manual run at 9am produce no duplicates.

Layout

| Path | What | |---|---| | `${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/radar/sources.yaml` | The source list (private, gitignored) | | `${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/radar/interests.local.md` | Global relevance context — what you care about right now | | `${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/radar/state/<source-id>.json` | Seen-item IDs + last run per source | | `${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/radar/runs/<date>.json` | Machine-readable run record (backs `promote`) | | `${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/radar/logs/<date>.log` | Unattended-run stdout, for debugging a silent morning | | `<vault>/outputs/radar/<YYYY-MM-DD>.md` | The human digest | | `<vault>/raw/<type>-<slug>.md` | Captured items, in second-brain's schema |

`<vault>` is `${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}`.

Step 0 — Parse mode

| Invocation | Mode | |---|---| | `/radar` / `/radar run` / "check my sources" / "run my radar" | **run** | | `/radar run <source-id>` | **run**, single source | | `/radar digest` / "what's new from my sources" | **digest** | | `/radar promote 3 7 12` / "promote item 4" / "capture the Isenberg one" | **promote** | | `/radar add <type> <target>` / "monitor this channel" / "watch r/SaaS" | **add** | | `/radar sources` / `/radar list` | **sources** | | `/radar pause <id>` / `/radar resume <id>` / `/radar remove <id>` | **manage** | | `/radar doctor` | **doctor** | | `/radar schedule` | **schedule** |

If `sources.yaml` doesn't exist in any mode but `add`/`schedule`, run first-time setup: copy `references/templates/sources.example.yaml` into place, create `state/`, `runs/`, `logs/`, then walk the user through adding their first 3–5 sources. Don't run against the example file's placeholder sources.

Read `references/sources-schema.md` before touching `sources.yaml` in any mode.

---

Mode: run

Step 1 — Load

1. Read `sources.yaml`. Filter to `enabled: true` sources whose `cadence` is due (compare against each state file's `last_run`; `daily` = due if last run was on an earlier calendar day). 2. Read `interests.local.md` — this is the global relevance context every item gets scored against, on top of each source's own `focus`. 3. Read each due source's state file. Missing state file = first run for that source; use `defaults.first_run_lookback_days` (default 3) instead of "since last run" so a new source doesn't dump its entire archive.

Step 2 — Fetch, in parallel

Read `references/fetchers.md` for the exact command per source type. Fetch every due source **in parallel** — they're independent, and a serial run over 15 sources is the difference between a 40-second morning job and a 6-minute one.

Rules that matter more than they look:

• **A failing source never fails the run.** Catch per-source errors, mark the source `degraded` with the error text, and carry on. A dead RSS feed must not cost you the YouTube results.
• **Cap per source** at `max_items_per_source` (default 15). If a source blew past the cap, say so in the digest — it usually means the lookback is too wide or the source got noisy.
• **Filter to new** by ID against the state file's `seen` list, then by `published` against the lookback window. Both, not either: IDs catch re-publishes, dates catch feeds that recycle IDs.
• **Every type has a dependable path now** — the free ones (youtube / rss / hn / bluesky / mastodon / reddit) plus X and LinkedIn via ScrapeCreators at ~$0.002 a call. A source that still exhausts its chain is marked `degraded` and skipped; don't retry in a loop, don't let it block the digest.
• **Filter X by `created_at`, never by position.** ScrapeCreators returns pinned and high-engagement tweets interleaved with recent ones — a single verified call put a 2024 tweet second. Trusting the order makes radar "discover" years-old posts as new.
• **Watch the credit balance.** Every ScrapeCreators response carries `credits_remaining`; record it in the run record and warn in the digest below ~1,000.
• **Check credentials once, at the start.** Resolve `AUTH_TOKEN`/`CT0` and any paid keys (env → OS keychain) before fetching, and skip the source types that need wh