// pinger

Concept — mobile detachable hub

v0.1 pinger is a fixed six-button control surface, hand-coded and Rocky-bound. v0.2 generalizes it: the rack is a frame, the buttons are data, the functions are a registry. The same widget becomes a media remote, a build runner, a localMesh dispatcher, a fast-launcher — by swapping its registry, not its code.

"Detachable" means the widget isn't bound to its launch node. Started on Rocky, it can be picked up and continued on aqua or quartz; the registry travels with it. Functions that are local to a host (e.g. start mini-mac on Rocky) get proxied back through localMesh; functions that are intrinsically portable (open URL, send mesh message) run wherever pinger is.

Architecture · topology

Architecture · registry shape

One button entry, one registry record. Stored as JSON, edited via GUI (see proposals below), persisted at ~/.pinger/registry.json (or wherever pinger currently is).

{
  "id": "ping",
  "label": "Ping!",
  "row": 1,
  "color": "primary",          // primary | secondary | danger | success | purple | custom
  "icon": "📡",                // optional emoji or path to png
  "hotkey": "F1",              // optional
  "scope": "remote@rocky",     // local | remote@<node> | mesh (any node)
  "command": {
    "type": "shell",           // shell | http | mesh-message | python | url
    "run":  "python ~/forge6/b33p/b33p.py identify vert"
  },
  "confirm": false,            // pop a "are you sure?" before firing
  "feedback": "chirp"          // chirp | toast | none
}

scope is the load-bearing field. local = run wherever pinger is. remote@rocky = proxy via localMesh to that node. mesh = broadcast or pick the right node from a hint. The frame doesn't care; only scope + command.type determine routing.

Architecture · click flow

Add / remove buttons via GUI — proposals

The frame is generic; the registry is the product. Three shapes for editing it without dropping to JSON.

Recommendation

B (edit drawer) on Rocky/desktop, A (inline) on aqua/Pebble. Same underlying registry, different surfacing per form factor. C (companion) earns its keep when registries grow past ~12 buttons or when sharing/importing button packs becomes a thing — defer until then.

Configure-a-button — the form behind "+ add"

All three proposals share the same form when you actually create or edit a button. The form is the only place a registry record gets shaped — proposals A/B/C just decide where it floats. Two modes: guided (default — dropdowns assemble the command for you) and raw (paste/edit the JSON directly).

┌─ new button ────────────────── ✕ ┐
│                                  │
│  LABEL                           │
│  ┌────────────────────────────┐  │
│  │ Ping!                      │  │
│  └────────────────────────────┘  │
│                                  │
│  COLOR     ROW                   │
│  [primary▾] [1 ▾]                │
│                                  │
│  ICON      HOTKEY                │
│  [📡]      [F1   ]               │
│                                  │
│  ─── what does it do ──────────  │
│                                  │
│  TYPE                            │
│  ( ) shell      ( ) http         │
│  (•) mesh-msg   ( ) python       │
│  ( ) url        ( ) chirp        │
│                                  │
│  RUNS ON                         │
│  ( ) local (wherever I am)       │
│  (•) remote@ [Rocky    ▾]        │
│  ( ) mesh   (any node)           │
│                                  │
│  TO       MESSAGE                │
│  [vert  ▾] [hey from pinger   ]  │
│                                  │
│  ─── on press ─────────────────  │
│                                  │
│  ☐ confirm before firing         │
│  FEEDBACK [chirp ▾]              │
│                                  │
│  [test it]   [cancel] [ save  ]  │
└──────────────────────────────────┘

┌─ new button ────── [guided|raw] ✕┐
│                                  │
│  ┌────────────────────────────┐  │
│  │ {                          │  │
│  │   "id": "ping",            │  │
│  │   "label": "Ping!",        │  │
│  │   "row": 1,                │  │
│  │   "color": "primary",      │  │
│  │   "icon": "📡",            │  │
│  │   "hotkey": "F1",          │  │
│  │   "scope": "remote@rocky", │  │
│  │   "command": {             │  │
│  │     "type": "mesh-msg",    │  │
│  │     "to": "vert",          │  │
│  │     "message": "hey from   │  │
│  │       pinger"              │  │
│  │   },                       │  │
│  │   "confirm": false,        │  │
│  │   "feedback": "chirp"      │  │
│  │ }                          │  │
│  └────────────────────────────┘  │
│  ✓ schema valid                  │
│                                  │
│  [test it]   [cancel] [ save  ]  │
└──────────────────────────────────┘

Field-by-field

• label · color · row · icon · hotkey — what the button looks like and how to fire it. all optional except label.
• type — picks the rest of the form. shell reveals a command-line input; http reveals method/url/headers/body; mesh-msg reveals to/message; python reveals a path-or-snippet input; url reveals the URL field; chirp reveals the b33p picker. Form is dynamic — only the fields the chosen type needs.
• runs on — sets scope. local = wherever pinger is right now. remote@<node> = always proxy to that node, regardless of where pinger lives. mesh = broadcast or pick from a hint.
• confirm — yes for HALT-class buttons, no for everything else.
• feedback — chirp (b33p), toast (silent banner), none.

Test-it flow

The [test it] button before save is load-bearing. It fires the command exactly as configured (respecting scope/proxy) and shows the result inline — exit code, stdout, error — without committing the button to the registry. Lets you iterate the command shape before paying the registry cost.

Function discovery shortcut (q3 preview)

Above the type radio, an optional "discover" chip:

┌────────────────────────────────────────────┐
│ ⌕ discover    "ping the agent vert"     ↵  │
└────────────────────────────────────────────┘
   suggests: type=mesh-msg, to=vert
             message="ping" (edit)
             [accept]  [skip]

Free-text intent → pinger queries known mesh capabilities (innate set + onMesh service registry) and pre-fills the form. Skip = fall through to manual. Tied to q3 — exists when discovery is wired, doesn't block the form's manual path.

Innate functions + onMesh discovery

Not every capability needs to be a registered button. Pinger ships with two layers of functions that exist below the registry, always available:

Layer 1 · innate (always on)

Pinger-level operations that don't belong in the user's button registry. Reachable from the gear menu in the titlebar regardless of what's been configured. Survive a wiped registry.

• about — version, registry path, mesh state
• edit — open the active edit surface (proposal A/B/C)
• profiles — switch / new / duplicate registry profile
• import · export — JSON registry in/out
• relocate — detach + travel to another mesh node (q2)
• onMesh — toggle live mesh awareness (default: on if localMesh reachable)
• ping self — fires the pinger's own chirp + statusbar flash; sanity check
• quit

Layer 2 · onMesh discovery (when toggle is on)

When onMesh is on, pinger introspects the localMesh service registry and exposes whatever's currently registered as ad-hoc fireable functions — without making them user-buttons. Two surfaces:

┌─ pinger ──────────── ⚙ ─┐
│ [Ping!] [Mac] [Stop  ] │   ← user registry
│ [stack] [snap] [HALT ] │
│ ─── services ─────────  │   ← onMesh layer
│ • pinger     /ping ⚡   │
│ • pingle     /ping ⚡   │
│ • mailbox    /ping ⚡   │
│ • registry   /ping ⚡   │
│ • messageRtr /ping ⚡   │
│  ⌕ filter…              │
│  ready · localMesh:8801 │
└─────────────────────────┘

┌─ pinger ──────────────────────┐
│ ┌───────────────────────────┐ │
│ │ ⌕ msg vert hey            │ │
│ └───────────────────────────┘ │
│  → mesh-msg · to=vert         │
│  → mesh-msg · to=vert.* (3)   │
│  → registry · ping vert       │
│                               │
│  recent:                      │
│   · ping pingle               │
│   · halt processFlow          │
│   · msg gourmand "ack"        │
│                               │
│  [↵ fire]   [⌘↵ promote]      │
└───────────────────────────────┘

The fire-ad-hoc / promote-to-button distinction

Important separation: the registry is your buttons — curated, reordered, themed. The mesh service list is the world's services — discovered, ephemeral, changes as nodes come and go. Pinger surfaces both but doesn't conflate them. Promotion is an explicit user action: "this mesh function is something I want a permanent button for."

This means onMesh = on with zero user-buttons is still a useful pinger — it's a mesh probe. And onMesh = off falls back to a pure user-registry remote (offline / privacy mode / when traveling outside the tailnet).

Open questions

Zero-hardcoded principle

Availability is the gate

A button bound to a mesh service only appears, and is only configurable, when that service is online. Concretely:

• The configure form's RUNS ON dropdown is populated from live mesh state. If Rocky isn't reachable, remote@rocky is not an option — period. You can't author a button for a service that isn't there.
• The TO dropdown for mesh-msg is filled from currently-registered agents. Offline agents drop out. No way to author a button addressed to nobody.
• In the rendered button list, mesh-bound buttons grey out (or hide, per setting) when their target goes offline. Tap a greyed button → status flash, no command sent.
• The services panel and command palette are mirrors of /registry/online. A service that's not running is not a function pinger knows about, full stop.

This makes "is this button safe to fire right now?" a property of the live mesh, not of the registry. The registry is intent; availability is reality.

Out of scope (this phase)

• Community button packs / sharing
• Per-button icons beyond emoji (PNG support, picker UI)
• pingerSLA migration — gated on this design landing
• Registry sync across nodes (each node has its own copy until q2 lands)