Email Sync Workflow
Pull Gmail into digest files under
raw/email/with entity detection for later wiki compilation.
The email-sync automation is the Gmail leg of the integration stack documented in recipes/email-to-brain.md. Source: automations/email-sync.md, 2026-05-31
Command
npx tsx scripts/sync-email.ts
Requires Google OAuth (run with --auth once). State and cursors live in ~/.kevin-wiki/integrations.pglite. Source: AGENTS.md Integration Recipes
Trigger And Inputs
Run every four hours through the local scheduler, or manually when Gmail freshness is stale. Required inputs:
- Google OAuth configured for Gmail readonly scope
scripts/sync-email.tsautomations/email-sync.md- existing wiki pages for person/company/project enrichment
Use npx tsx scripts/sync-email.ts --auth only when credentials are missing or expired.
Runbook
- Read
automations/email-sync.md. - Run:
npx tsx scripts/sync-email.ts - Read the new or touched digest files in
raw/email/. - Extract:
- signature requests
- reply-needed items
- people and companies worth enriching
- project/career/fundraising facts that should survive beyond the inbox
- Search existing wiki pages before creating anything.
- Promote only facts that meet the matrix below.
- Write
outputs/<YYYY-MM-DD>/email-sync/codex.md. - Update
state.json:syncs.emailis handled by the collector on successful collectionautomations.email-syncshould be the current ISO timestamp after the scheduled check completes
- Append
wiki/log.md. - If wiki pages changed, run
npx tsx scripts/build-index.tsandqmd update && qmd embed.
What it produces
- Markdown digests in
raw/email/ - Detected people, companies, and threads worth entity pages
- Dedup via integration DB so reruns are idempotent
Promotion Matrix
| Email signal | Durable action |
|---|---|
| Real person already represented in the wiki | Add a concise dated timeline entry when the email changes context. |
| Repeated sender/company with professional relevance | Create or update person/company page after alias search. |
| Signature or contract request | Keep in output action list unless it changes a project/career page. |
| Recruiter, investor, collaborator, or role signal | Update career, person, company, or project page when it changes strategy. |
| Automated notification, newsletter, receipt, calendar mail | Keep in digest/noise; do not promote. |
Downstream
Raw digests are immutable. Compilation into wiki/people/, wiki/career/, wiki/projects/, and related pages follows this workflow, Source Compile Workflow, or manual ingest with markAbsorbed() when a raw email digest becomes cited source material.
Schedule: every four hours for the local Codex runner. Successful collection updates syncs.email; scheduled run completion updates automations.email-sync with an ISO timestamp.
Failure Handling
| Failure | Response |
|---|---|
| Missing Google account | Run npx tsx scripts/sync-email.ts --auth interactively or record blocker; do not update syncs.email. |
| Token refresh failure | Record the failing account and leave sync freshness stale. |
| No new email | Write No durable wiki update needed; still update automation timestamp after successful check. |
| Digest has sensitive low-signal content | Summarize action/result only; do not quote private text into wiki pages. |
| Entity match ambiguous | Leave as output-only follow-up instead of creating a duplicate page. |
Validation
After a scheduler or workflow change:
npx tsx scripts/check-freshness.ts
sqlite3 ~/.codex/sqlite/codex-dev.db "SELECT id, status, rrule FROM automations WHERE id = 'email-sync';"
For manual collection proof, inspect the newest raw/email/<YYYY-MM-DD>.md and confirm state.json syncs.email advanced.
Closeout
Email sync closes only after the collector result, output artifact, promotion/no-op decision, and state writes are visible. Durable promotions require Build Index Workflow and QMD Embed Workflow. If repeated email patterns reveal a new follow-up loop, update the relevant workflow or automation instead of adding another reminder to the ether.
Run Contract
This workflow follows Workflow Run Contract: name the sources, write output or no-op proof, promote only durable facts, update state only when the run really completed, refresh generated surfaces when durable pages or skills change, and log user-visible work.
Timeline
- 2026-07-01 | Added workflow-run closeout expectations for collector proof, output artifact, promotion/no-op decision, state writes, and generated search refresh. Source: User request, 2026-07-01
- 2026-06-30 | Updated the workflow for the every-four-hours Gmail sync loop and ISO automation timestamps. Source: User request, 2026-06-30;
automations/email-sync.md - 2026-05-31 | Workflow page created from email-sync automation and email-to-brain recipe. Source: automations/email-sync.md, 2026-05-31