@meta
  v: 1
  route: /warlock-buddy
  generated: 2026-06-09T00:00:00Z
  ttl: 1h

@intent
  purpose:    Warlock Buddy — a desk-side M5Stack CoreS3 command surface for the Warlock deck. A hacker-HUD that mirrors the engagement gate and lets an operator ARM a scoped engagement, END it, or fire the KILLSWITCH with a physical tap. The desk-side sibling to the Warlock deck and the Wisp wand.
  audience:   msp, security-pro, agent
  capability: read, build, evaluate

@state
  status: active
  form_factor: M5Stack CoreS3 (ESP32-S3) desk companion + Bun BLE bridge
  tagline: "The deck's engagement gate, on your desk."
  how_it_works: "CoreS3 speaks BLE (Nordic UART, JSON) to a Bun bridge; the bridge polls the Warlock API and relays gate commands back to the deck's existing audited endpoints. Run the bridge on the deck itself (CM5 onboard Bluetooth) for a direct pairing — no second machine."
  features[6]{capability,detail}:
    gate-banner,"Hero banner mirrors the gate — SAFE (green), ATTENTION (amber, engagements staged), ARMED (red, pulsing), OFFLINE (gray)"
    tap-gate,"Tap-twice confirm to ARM a staged engagement, END the active one, or fire the KILLSWITCH; NEXT cycles staged engagements"
    telemetry,"Live deck telemetry — active scope (ssid/bssid/cidr), SIGILS (signed AAR count), CPU temp / cpu% / mem% / mesh nodes / GPS fix / SDR count, uplink heartbeat"
    consumer-side,"Uses only the deck's existing audited endpoints (engagements activate/end, killswitch, dashboard/status, aar/status) — adds no new backend surface"
    pairs-to-deck,"Pairs straight to the deck over the CM5 onboard Bluetooth (BT 5.0/BLE); the AC1200 stays on monitor-mode Wi-Fi duty"
    ask-the-deck,"Roadmap — on-device LLM Q&A via the stacked Module-LLM (AX630C) over UART"
  hardware[5]{component,detail}:
    host,"M5Stack CoreS3 — ESP32-S3, 320x240 capacitive touch, speaker, IMU"
    link,"Bluetooth LE — Nordic UART Service (JSON), CoreS3 to bridge"
    bridge,"Bun + noble — runs on the deck (systemd, CM5 onboard BT) or any nearby host in BLE range with network access to the deck API"
    firmware,"Arduino / PlatformIO (M5Unified); build-your-own from documented source"
    roadmap,"Stacked Module-LLM (AX630C) for on-device 'ask the deck'"
  safety[3]{control,detail}:
    consumer-side-only,The buddy calls only the deck's existing gated endpoints — it can do nothing the operator could not already authorize
    deliberate-confirm,ARM / END / KILLSWITCH each require a tap-twice confirm to prevent an accidental trigger
    audited,Every armed action is recorded by the deck as a signed AAR attestation, exactly as if driven from the web UI or TUI

@actions
  - id: view_human
    method: GET
    href: /warlock-buddy.html
  - id: view_source
    method: GET
    href: https://github.com/techmages-org/warlock-buddy
  - id: the_deck
    method: GET
    href: /warlock.html

@context
  > Warlock Buddy is a desk-side M5Stack CoreS3 that makes the Warlock deck's engagement gate tactile. A hacker-HUD (black CRT, phosphor green) shows the deck's posture at a glance — SAFE, ATTENTION when engagements are staged, ARMED when one is live, OFFLINE when the deck is unreachable — alongside live telemetry: the active scope, the count of signed AAR attestations ("sigils"), and deck temp/cpu/mem/mesh/gps/sdr. A tap-twice gate lets the operator ARM a pre-staged engagement, END it, or fire the kill switch; those commands ride back over Bluetooth to the deck's existing, audited endpoints, so the buddy adds no new backend surface and can do nothing the operator couldn't already authorize. A small Bun bridge relays BLE-to-HTTP; run it on the deck itself and the CM5's onboard Bluetooth pairs to the buddy directly, with no second machine in the loop. It is the desk-side sibling to the Warlock deck (the brain) and Wisp (the wand). Build-your-own from documented source on an off-the-shelf CoreS3.

@nav
  self:      /warlock-buddy.agent
  parents:   [/.agent]
  peers:     [/warlock.agent, /wisp.agent, /deck.agent, /deck-gui.agent, /projects.agent, /index.agent, /charter.agent, /contribute.agent]