Configuration

nicheclock reads one YAML file. init writes it, you edit it. Paths in it are resolved against the folder the file is in. Pick the file with --config (or -c), the NICHECLOCK_CONFIG environment variable, or ./nicheclock.yaml, in that order.

Secrets never go into the file. Fields that need one name an environment variable (token_env: TG_TOKEN) or a file (token_file: path) instead.

The whole file

identity:
  user_agent: "mysite-radar/1.0 (+mailto:you@example.com)"   # required before any fetch
  contact_email: you@example.com                              # required before any fetch
data_dir: ./data              # SQLite database and caches
out_dir: ./out                # reports: <out_dir>/<project>/{feed.json,feed.md,index.html,feed.xml}
default_lag_days: 3           # index lag used for publish_by until Search Console gives a measured one
projects:
  - name: example
    urls: [https://example.com]
    schedule: daily           # recorded for your scheduler; `run` does not read it (see Limitations)
    regions: [global]         # or country codes such as [US, GB]; see Regions
    niches:
      - name: birdwatching
        keywords: [birdwatching, bird watching]    # phrases that make an item relevant
        entities: [Snowy owl]                    # specific things, as Wikipedia titles where possible
        context: [Bird]                    # broad terms: count only next to a keyword or entity
        formats: [field guide, checklist]  # content formats, shown in the report, never matched as topics
        exclude: [tips, beginner]          # an item containing one of these is dropped
        sources: [google_trends, wikipedia, hn, github, gdelt]
        rss: []                            # feeds you supply (titles, links and dates only are kept)
        watch: []                          # feeds where any keyword hit is enough
        ics: []                            # calendars for the Upcoming table
        upcoming: true
        options: {geo: [US], hn_min_points: 50}
llm: null                     # your model, see Models; null means no model call, ever

Validate it any time with nicheclock doctor (add --offline to skip the network checks).

Fields

nicheclock edit changes any of the list fields without opening an editor: --add-keyword, --remove-keyword, and the same for entity, format, exclude, source, rss, watch, ics. It also has --add-niche, --rename-niche, --remove-niche, --add-url, --remove-url, --add-notify and --preview. Run nicheclock edit --help for the full list.

Per-source options

Under niches[].options:

How a topic gets into the feed

Keywords and entities decide relevance. Fuzzy full-text searches (Hacker News, GitHub, GDELT, Federal Register) must contain a keyword or entity in the title. A topic then needs to clear a floor. Any one of these is enough:

• a specific entity;
• a keyword plus strength: Hacker News 100 points or more, Google Trends top 10, a Wikipedia riser at 2x, GDELT news volume at 2x the four-week mean, a Federal Register title naming the keyword, or a specific multi-word keyword in a headline;
• any keyword in an item of a feed under watch:;
• two distinct hits;
• one keyword seen in two source families.

Abstract-only Federal Register matches go to low_confidence in feed.json. Kept signals are stored in SQLite at <data_dir>/nicheclock.db.

GDELT is one global queue: ten seconds between requests, answers cached 24 hours. When it rate-limits you, the rest of the queue is saved to <data_dir>/cache/gdelt_queue.json and goes first in the next run.

What run writes

For each project, under <out_dir>/<project>/:

<out_dir>/index.html links all projects. Exit status: 0 when everything worked, 1 when one or more sources failed (the files are still written), 2 for a configuration problem such as a missing identity.

Notifications

run sends each channel the top top_n (default 5) new items per niche, with the why and a link. Items already sent to a channel are skipped; the log lives at <data_dir>/<project>/notify_sent.json and entries expire after 90 days. A failing channel is reported and retried next run; it never blocks the others. --no-notify skips them for one run.

notify:
  - {type: telegram, token_env: TG_TOKEN, chat_id: "-100123", top_n: 5}
  - {type: discord, webhook_env: DISCORD_WEBHOOK, kinds: [topic, event]}
  - type: email
    host: smtp.example.com
    port: 587                    # 587 STARTTLS (default), 465 with security: ssl
    security: starttls           # starttls | ssl | none
    username: me@example.com
    password_env: SMTP_PASSWORD  # or password_file
    from: me@example.com
    to: [me@example.com]

Optional on every channel: top_n, kinds: [topic|event|gap], min_score. Telegram also takes api_base and message_thread_id; email takes ca_file for a private CA.

Project-level fields

regions and region_mode (per project, overridable per niche) choose which countries are read and whether each gets its own topics; see Regions.

schedule is stored for you and for your scheduler; nothing inside nicheclock reads it yet. gsc connects Search Console. profile (title, description) tells a model who the site is. llm configures your model.