Cron Actions & Maintenance Reference
Quick reference for every scheduled job, maintenance check, and index regeneration script in Eko. Use this to know what runs when, what to run after changes, and how to set up recurring dev-session monitoring with /loop.
See also: APP-CONTROL.md for the full operational manifest with dependencies, env vars, and YAML directives.
1. Production Crons
1a. Scheduled (vercel.json) — 5 routes
These fire automatically on production deploys. Defined in apps/web/vercel.json.
| Route | Schedule | Description |
|---|---|---|
/api/cron/payment-reminders | 0 9 * * * (daily 9 AM UTC) | Send renewal reminder emails (7d, 3d, 1d before expiry) |
/api/cron/payment-escalation | 0 9 * * * (daily 9 AM UTC) | Escalation emails for past-due subscriptions |
/api/cron/account-anniversaries | 0 9 * * * (daily 9 AM UTC) | Milestone notifications (1w, 1m, 3m, 6m, 1y) |
/api/cron/daily-cost-report | 0 6 * * * (daily 6 AM UTC) | Email admins AI cost breakdown with 7-day trend |
/api/cron/monthly-usage-report | 0 9 1 * * (1st of month) | DEPRECATED — No-op stub; remove from vercel.json |
1b. Unscheduled (route exists, not in vercel.json) — 8 routes
Must be triggered manually, added to the scheduler, or handled by external orchestration.
| Route | Intended Schedule | Description |
|---|---|---|
/api/cron/ingest-news | */15 * * * * (every 15 min) | Enqueue INGEST_NEWS for configured providers × active topics |
/api/cron/cluster-sweep | 0 * * * * (hourly) | Batch unclustered sources → enqueue CLUSTER_STORIES |
/api/cron/generate-evergreen | 0 3 * * * (daily 3 AM UTC) | Enqueue GENERATE_EVERGREEN per active topic (gated by EVERGREEN_ENABLED) |
/api/cron/validation-retry | 0 */4 * * * (every 4 hours) | Re-enqueue stuck validations (>4h without update) |
/api/cron/archive-content | 0 2 * * * (daily 2 AM UTC) | Archive expired facts; promote high-engagement facts to enduring |
/api/cron/topic-quotas | 0 6 * * * (daily 6 AM UTC) | Audit daily fact counts vs topic quotas (monitoring only) |
/api/cron/import-facts | 0 4 * * * (daily 4 AM UTC) | STUB — Placeholder for structured API imports (ESPN, WikiQuote, GeoNames) |
/api/cron/daily-digest | — | DEPRECATED — v1 stub; safe to delete |
2. Weekly Maintenance Checks
Run these weekly (or before PRs) to catch documentation drift and architecture violations.
| Command | What It Checks |
|---|---|
bun run docs:health | Documentation health score (CI threshold: 95%) |
bun run docs:links | Broken internal doc links |
bun run agents:routing-check | Agent file ownership and routing table integrity |
bun run bible:check | Product bible structural integrity |
bun run check-invariants | Eko architecture invariants (fact-first, verification, etc.) |
One-liner:
bun run docs:health && bun run docs:links && bun run agents:routing-check && bun run bible:check && bun run check-invariants
3. After-Change Triggers
Run the relevant command after modifying the associated files. CI will fail if indexes are stale.
| Trigger | Command | When to Run |
|---|---|---|
| Migration files changed | bun run migrations:index | After creating/modifying files in supabase/migrations/ |
| Scripts changed | bun run scripts:index | After adding/removing scripts in scripts/ |
| Rules changed | bun run rules:index | After adding/removing files in docs/rules/ |
| DB schema changed | bun run db:types | After applying migrations or schema changes |
| UI registry changed | bun run registry:export | After modifying packages/ui/ component exports |
4. Monthly / Quarterly Checks
Lower-frequency audits for content coverage and code quality.
| Command | Frequency | What It Checks |
|---|---|---|
bun run taxonomy:completeness-check | Monthly | Topic taxonomy coverage gaps (also runs in CI) |
bun run check-error-handling | Quarterly | Error handling patterns across the codebase |
bun run docs:staleness | Monthly | Documentation freshness by last-modified age |
5. /loop Recipes
Copy-paste these into a Claude Code session for recurring monitoring.
Deployment & CI
/loop 5m bun run soak:status
Watch soak test progress after kicking one off.
/loop 3m vercel logs
Monitor a fresh deployment for errors.
/loop 5m Check CI status on my PR
Poll GitHub Actions until green.
Development Workflow
/loop 10m bun run typecheck
Catch type errors as you work across packages.
/loop 5m bun run lint
Continuous lint feedback during a refactor session.
Data & Pipeline Ops
/loop 5m Check Upstash queue depth and worker health
Poll queue backlogs during ingestion runs.
/loop 10m bun run test:news
Continuous news ingestion smoke test.
/loop 15m Check fact validation pipeline progress
Monitor batch validation runs.
6. When to Use What
| Mechanism | Best For | Example |
|---|---|---|
| Vercel cron | Production-scheduled work (billing, reports, ingestion) | payment-reminders at 9 AM daily |
/loop | Dev-session monitoring; temporary recurring checks | /loop 5m bun run typecheck during refactors |
| Claude hooks | Enforcing rules on every tool call (pre/post commit, pre-edit) | Prevent editing locked plans |
Shell watch | Quick terminal polling outside Claude Code | watch -n 30 curl -s localhost:8080/health |
CI (bun run ci) | Gate merges; full validation suite | PR checks, branch protection |
Decision Flowchart
- Needs to run in production on a schedule? → Vercel cron (
vercel.json) - Needs to run on every code change/commit? → Hook (
.claude/hooks/or Husky) - Needs to run during a dev session repeatedly? →
/loop - One-off terminal check? → Just run the command or use
watch - Must gate a merge? → Add to the
ciscript inpackage.json