Commander Bots — Live API Integration

  period: project
  owner: jimmy-neutron
  status: scoping
  task: #840060
  created: 2026-05-26

Why This Exists

The Telegram Commander bots (bulma/ging/zuko/brook/sanji/squidward) reply IN-VOICE using each Commander's context.md as system prompt. They do NOT pull live data. This doc audits the gap + sequences the work to connect each bot to its live data source.

Current State vs End-State

  CommanderDomainCurrent sourceAPI targetPull cadence

    Bulmafinance, budgetingcontext.mdMonzo (poll-monzo.py shipped, awaits OAuth verify) + TrueLayer (#600011)per-message live pull
    Gingreadingcontext.mdReadwise API, Apple Books export, or Pocketdigest of what I've read this week
    Zukocareer, job searchcontext.mdLinkedIn (limited); local jobs.csvapplications-this-week + interview pipeline
    BrookTV/film/gamescontext.mdTrakt.tv + MAL + Steamrecent watch-history, recommendations
    Sanjinutrition, mealscontext.mdOpen Food Facts (free) or photo-based logging via Whisper-on-captionmacros today, last meal logged
    Squidwardmusic practicecontext.mdSpotify (top tracks), local practice-log.csvminutes-practiced-today, recent repertoire focus

Integration Shape (uniform across all Commanders)

Each Commander gets a pull-{commander}.py script that produces a small JSON snapshot Studio + the bot poller both read:

~/Sandpit/hinata/scripts/pull-{commander}.py
  └─→ ~/Sandpit/hinata/data/{commander}/snapshot.json
  └─→ applications/hinata-studio/public/data/{commander}-snapshot.json

Bot-poller extension: when replying as Commander X, load {commander}-snapshot.json into the system prompt under a ## live context section. Snapshot has timestamp so bot can say "as of 14:32 today, your Monzo balance is …".

Sequencing

  WaveCommandersRationale

    Wave 1 (in-flight)BulmaMonzo + TrueLayer tokens already captured; poll-monzo slice 1 shipped. Closes #600010, #600011.
    Wave 2Brook, SquidwardTrakt + MAL have generous free tiers; Spotify OAuth is straightforward.
    Wave 3Sanji, SplinterOpen Food Facts (Sanji) + Readwise (Splinter) — free tiers, well-documented APIs.
    Wave 4Zuko, SimbaHardest — no clean APIs. Zuko reads local job-applications/ folder; Simba reads subscription roster.

Closure Trigger (#840060)

1. All 7 Commanders have a pull-{commander}.py producer running on a LaunchAgent

2. All 7 produce snapshot.json of useful shape

3. hinata-bot-poller.py reads snapshots into system prompts

4. Michael verifies by asking each bot a question whose answer requires live data and gets a fact-grounded reply

   ◆ hinata · projects/commander-api-integration.html · phase-18 flatten