From 7eef9141332911cf7f48dd826cf08d8e2277052d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 18 Jul 2026 21:07:37 +0000 Subject: [PATCH] docs: add feature-led IoT integration shortlist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit IoT only earns a place when it unlocks Scanner Inbox, batch-landed nudges, or shift-close packets — not connect-only logos. Link from the integrations roadmap; no shipped claims. Co-authored-by: Muhammad Rafiq --- docs/integrations-roadmap.md | 9 ++ docs/iot-integrations.md | 191 +++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+) create mode 100644 docs/iot-integrations.md diff --git a/docs/integrations-roadmap.md b/docs/integrations-roadmap.md index 725ddd3..2244980 100644 --- a/docs/integrations-roadmap.md +++ b/docs/integrations-roadmap.md @@ -155,6 +155,15 @@ Ghost-initiated reads/exports (e.g. writing an audit export to a bucket the user already owns), and treat any inbound trigger as subject to full policy review before it can propose a mutation. +## IoT (feature-led, not logo-led) + +Internet of Things work is planned as **Ghost features** (Scanner Inbox, batch +landed nudges, shift-close packets) that use devices/hubs only as intent +sources — never as silent actuators. Connectivity without a user job is out of +scope. Shortlist, filter, and intent contract: `docs/iot-integrations.md`. +Nothing there is shipped in the default product; the closest built signal path +is the experimental Fabric inbound webhook (`docs/fabric-eventstream-webhook.md`). + ## AI-assistant connectors (Claude, Cursor, Codex, ChatGPT) These are different in kind from Fabric/Google Cloud: they're coding/agent diff --git a/docs/iot-integrations.md b/docs/iot-integrations.md new file mode 100644 index 0000000..87cc5bd --- /dev/null +++ b/docs/iot-integrations.md @@ -0,0 +1,191 @@ +# IoT integrations (feature-led) + +Internet of Things ideas for Ghost only ship when they unlock a **user job** +Ghost already owns (file, verify, replay, audit) — not when they add a logo. + +Devices and hubs may **propose**. Ghost still runs: + +```text +Intent -> Plan -> Policy check -> User approval -> Execution -> Audit log -> Undo +``` + +Nothing in this doc is a shipped product claim. Stock Ghost does not bundle +scanner SDKs, POS drivers, or an MQTT broker. See `docs/integrations-roadmap.md` +for what is actually built (Fabric inbound webhook is the closest existing +signal path). + +## Filter + +Ship an IoT-backed idea only if all are true: + +1. **Job** — removes a repeated desk/ops step (filing, closeout, verify). +2. **Delta** — better than “user opens Ghost and clicks Scan” alone. +3. **Trust** — device never auto-executes; Approve stays on the desktop. +4. **Honesty** — demoable without certification, always-on cam/mic, or silent + OS control claims. + +Connect-only ideas fail this filter and are listed under [Rejected](#rejected). + +## Features + +### F1 — Scanner Inbox (P0) + +**Job:** Paper becomes files and a reviewable filing plan is waiting — the +bookkeeper does not hunt folders or remember to run Organizer. + +**User-visible behavior:** + +- Preset Zone “Scanner Inbox” on the MFP / ScanSnap drop folder. +- New files → inbound intent (or local “new files since last plan” signal). +- UI: badge / card “N new scans ready to file” with **Create plan** (not + auto-move) → Approve → Organizer execute → audit / undo. + +**Signal (thinnest path):** local scan-to-folder. No vendor SDK required for +v1 — Brother / Fujitsu / HP / Epson that drop PDF/JPEG into a directory are +enough. + +**Ghost modules:** Organizer Zones + planner/executor; Zone preset + docs; +optional inbound-intent card. + +**Risk:** plan creation is read/plan; execute stays `local-mutate` with +approval. No camera permission. + +**Demo one-liner:** Drop three invoices into the scan folder → Ghost shows a +plan → approve → files land under Finance with audit. + +### F2 — Batch landed nudge (P0) + +**Job:** When an export, SFTP drop, or nightly pipeline finishes, Ghost prompts +filing (or a saved-routine preview) instead of ignored chat noise. + +**User-visible behavior:** + +- Intent card: “Nightly AP export landed — review Zone …” +- Actions: **Create plan** | Dismiss. Never auto-execute. +- Later: deep-link to a named routine preview (still Approve). + +**Signal:** ops webhook / Fabric Eventstream bridge → Ghost inbound intent +(`docs/fabric-eventstream-webhook.md`). Specialize on **document/batch +completion** events, not sensor novelty demos. + +**Ghost modules:** Fabric (or future generic) inbound queue; Organizer banner; +experimental MCP HTTP listener for `POST /fabric/webhook`. + +**Risk:** recording an intent is not mutation; convert = plan only. + +**Demo one-liner:** Bridge posts “pipeline done” → Organizer card → Create +plan → approve. + +### F3 — End-of-shift desk packet (P1) + +**Job:** At register/POS close, Ghost assembles today’s filing plan (and +optional checklist routine) so closeout is not tribal knowledge. + +**User-visible behavior:** + +- Trigger: POS *close / settlement* webhook via a bridge (not Ghost inside the + POS). +- Intent: “Shift closed — file today’s receipts.” +- Opens Organizer plan for the day’s drop Zone; optional routine checklist + preview. + +**Explicit non-goal:** Ghost must not type into the POS from a cloud event. +Guard Desk / POS Bridge remains a **prototype desk workflow — not certified +compliance** (`docs/audiences.md`, product audits). + +**Delta vs F1:** time-bound “today’s batch” + closeout checklist, not every +scan. + +### F4 — File-and-label (P2) + +**Job:** After an approved Organizer run, optional folder/box label so physical +and digital filing match. + +**User-visible behavior:** + +- Post-run optional step: preview label text (path, period, client) → Approve + print → DYMO / Brother QL / CUPS. +- Audit note: “label printed for run X.” Paper is not undoable — say so in UI. + +**Ship only if** F1/F2 are habitual; otherwise it is a peripheral toy. + +**Risk:** device I/O after explicit approval; treat as higher than pure FS +move; gate experimental. + +### F5 — On-demand check/ID assist (P2, prototype-honest) + +**Job:** User presents a check or ID image; Ghost OCR/parses into a review +packet; user decides next steps. + +**User-visible behavior:** Existing on-device OCR + ID parse +(`run_ocr_on_image`, `parse_id_document`) and Guard Desk UI. IoT angle = +tethered imager as an **explicit user gesture** to supply bytes — never +ambient camera. + +**Do not** market as KYC/AML/sanctions or compliance certification. + +## Priority table + +| Priority | Feature | Ghost surface | Mechanism | Status | +|---|---|---|---|---| +| P0 | F1 Scanner Inbox | Organizer | Scan-folder Zone preset + new-files → plan | Design; Zone path works today without new commands | +| P0 | F2 Batch landed | Inbound intent → plan | Fabric/ops webhook bridge | Partial (Fabric intent queue, experimental) | +| P1 | F3 Shift close packet | Intent → Zone/routine preview | POS close webhook → bridge | Not built; marketing must stay qualified | +| P2 | F4 File-and-label | Post-run optional print | Label printer after Approve | Not built | +| P2 | F5 Check/ID assist | Guard Desk | User-supplied image OCR | Partial core OCR; desk workflow prototype | + +## Intent contract (when a feature needs a signal) + +Integrations that cannot use a plain folder watch should emit Ghost-native +JSON (same spirit as Fabric inbound): + +```json +{ + "source": "scanner.folder|ops.pipeline|pos.close|hub.bridge", + "summary": "12 new scans in Inbox", + "zone_id": "optional-ghost-zone-uuid", + "dedupe_key": "optional-stable-id", + "payload_ref": "optional-path-or-uri-not-file-bytes" +} +``` + +Rules: + +- No file bytes in the intent; paths only if already inside an allowed Zone. +- Statuses: `Pending` → `Converted` (user asked for a plan) / `Dismissed` / + `Expired`. +- `Converted` means plan creation only; execute still requires Approve. +- Prefer hubs (Zapier, Make, Node-RED, Home Assistant, Azure Function) as + **bridges** over first-party SDKs per gadget. + +## Rejected + +| Idea | Why it fails | +|---|---| +| Smart lights, thermostats, vacuums, speakers | No Ghost job | +| Always-on security cams, doorbells, microphones | Privacy non-negotiable | +| “Works with Azure IoT” badge without F2 cards | Connect-only | +| Cloud event → direct POS / OS input | Silent `os-control`; burns trust | +| Embed MQTT / IoT Hub client in Ghost core | Infra without a user job | +| Industrial PLC / SCADA control | Wrong product | +| Ambient home automation as a Ghost surface | Wrong audience and thesis | + +## Implementation order (after this design) + +1. **F1** — document + Zone preset “Scanner Inbox”; optional new-files intent + card (folder watch before any scanner SDK). +2. **F2** — harden inbound intent UX (multi-intent list, Create plan = + `Converted`); keep `/fabric/webhook`; generic alias only when needed. +3. **F3** — POS close → same intent queue; no POS key injection. +4. **F4 / F5** — only with clear habit and honest labeling. + +Separate PRs per feature. Do not bundle with AI suggestions or marketplace +work. + +## Related docs + +- `docs/integrations-roadmap.md` — account / Fabric / GCS / MCP reality +- `docs/fabric-eventstream-webhook.md` — inbound intent bridge pattern +- `docs/organizer-planner.md` / `docs/organizer-executor.md` — trust pipeline +- `docs/core-boundaries.md` — stable vs experimental; OCR scope +- `docs/audiences.md` — what stays off the public surface