Feature: remote capture from phone — voice notes, images & links + thoughts via direct-to-intake

[wimaan3]

Context

Capture ideas away from the desktop: send a voice note, an image, or a link (e.g. an Instagram post URL) plus some accompanying thoughts from a phone, and have grandplan organize it into a note like any hotkey capture — media preserved as attachments, URLs preserved as link resources.

Transport decision: direct-to-intake — a phone shortcut / minimal PWA that POSTs to the existing HTTP intake (src/grandplan/adapters/http_intake.py) over a private network (Tailscale/WireGuard or LAN). No messenger platform in the loop: content never transits a third-party cloud, so the offline/zero-egress invariant holds end-to-end (QAS-1). The core app still never makes an outbound request.

Much of this exists already:

• http_intake.py — token-authed (constant-time), 127.0.0.1-default intake built exactly for "POST content from a phone over LAN/VPN".
• voice.py — offline STT via faster-whisper (grandplan[voice]); mic-based today, but the same local model transcribes an audio file.
• The organizer's resources pipeline already extracts URLs present in the capture text into the note's ## Resources block (with the anti-hallucination containment check), so "thoughts + IG link" → link lands in the note with no new code.

Threads

• Attachments over intake — accept media alongside text (multipart or size-capped base64 field; current 1 MiB body cap must be rethought for voice notes/images, with an explicit new cap). Persist media into a vault attachments dir; reference from the note as file resources. Reject unexpected content types; never execute/render untrusted content.
• Voice-note transcription — route received audio files through a file-based Transcriber (reuse faster-whisper, local, offline). Transcript becomes the capture text (plus any typed thoughts); original audio kept as an attachment (lossless: the source artifact is preserved).
• Image + thoughts (v1) — store the image as an attachment resource; the accompanying text is the capture. (v2, deferred: optional local vision model to describe/extract — new multi-GB model on the 16 GB no-GPU target, needs its own evaluation.)
• Phone-side sender — an iOS/Android Shortcut recipe and/or a single-file PWA served by the intake (share-sheet friendly: share a post/photo/voice memo → adds thoughts → POST). Documented setup for Tailscale/WireGuard reachability.

Acceptance criteria

• A voice note POSTed from a phone becomes an organized note whose body is the local transcript; the audio file is saved in the vault and linked as a resource.
• An image + text POST becomes a note with the image attached and linked.
• Text containing a URL (e.g. an Instagram post) yields a note with that URL in ## Resources (existing behavior verified through the new path).
• Intake stays token-gated and 127.0.0.1 by default; media size/type limits enforced before reading the body; auth failures leak nothing.
• Zero network egress from grandplan itself — nothing is fetched; the app only receives. Fully offline processing (Whisper local).
• Works on the 16 GB / no-GPU target.

Non-goals (for this issue)

• Messenger-platform bridges (Telegram/WhatsApp bots). Considered and deferred: they route content through third-party clouds; if ever built, it would be a separate optional companion process, never core.
• Vision-model understanding of images (v2 candidate).
• Fetching remote content from shared URLs (violates zero-egress; the link itself is the artifact).

Related

• Sits after the capture-latency work (Research: local-model selection, fine-tuning & optimization for grandplan's tasks #34 and the pipeline call-count reduction) — remote capture feeds the same organize pipeline, so per-note speed lands first.
• Media/attachment groundwork may inform Feature: converse with the vault — retrieve, turn notes into plans, clean up notes #36 (converse with the vault) retrieval over transcripts.

[wimaan3]

Transport analysis: capture from outside the home network (cellular/public wifi)

Requirement refinement: captures must work away from home (cellular / café wifi), without ever exposing the vault or the intake to the public internet.

Decision: overlay VPN (Tailscale/WireGuard) remains the v1 transport — it already covers the away-from-home case. Phone and vault machine form a private encrypted network over any connection; the intake stays bound to a private address with token auth on top. No open ports, no public IP, no time-boxed exposure.

Rejected: a temporarily-opened public port ("open for 30 minutes"). Time-boxed public exposure is still public exposure (internet-wide scanners probe new ports within minutes), requires TLS + hardening, and fails unsafe if the window is forgotten. An overlay tunnel provides the same reachability permanently with none of that surface.

Known gap in v1: the vault machine must be awake when a capture is sent. Mitigations, in order:

1. v1 — phone-side queue: the sender (shortcut/PWA) persists the capture locally and retries until the intake is reachable. No infrastructure, nothing lost.
2. v2 — encrypted store-and-forward (optional companion, NOT core): phone drops client-side encrypted blobs on a dumb relay (own VPS / object bucket — relay only ever sees ciphertext); an opt-in companion process at home pulls (outbound-only), decrypts locally, feeds the intake. Core grandplan keeps zero egress; the puller is a separate process like the senders.
3. v2 zero-server variant: Syncthing (P2P, E2E-encrypted) syncing a captures folder phone→PC, ingested by the existing folder_watch adapter — near-zero new code; sync self-queues while the PC sleeps.

Invariants preserved in all variants: vault machine accepts no public inbound connections; core grandplan makes no outbound requests; captures are encrypted in transit end-to-end; media/originals land losslessly in the vault.

[wimaan3]

Transport decision: self-hosted Headscale (coordination, on a home device) + open-source Tailscale clients, WireGuard encryption underneath. No vendor SaaS — content and metadata stay on owned hardware. Embedded DERP so even relay fallback is self-hosted. The only internet-reachable endpoint is Headscale's TLS control plane; the intake and vault are never exposed. Full runbook: docs/notes/REMOTE-CAPTURE-TRANSPORT.md. Plain WireGuard (single silent UDP port, zero servers) stays on record as the simpler fallback; the app is transport-agnostic either way.

[wimaan3]

LAN-first slice shipped (c21bbbd): POST /capture on the intake server — text / voice notes (offline Whisper transcription, audio kept verbatim) / images (+ thoughts) from a phone on the same wifi → organized note with linked attachments. Security pinned by tests AND verified against a live server: 401 pre-body without token, 413 per-route caps pre-read, traversal-sanitized names (verified nothing escapes attachments/), extension allow-list, 500-never-hang on server errors, routable-bind-requires-token unchanged. LAN quickstart added to docs/notes/REMOTE-CAPTURE-TRANSPORT.md.

Remaining on this issue (per maintainer: validate LAN first, then expand): phone-side sender convenience (iOS Shortcut recipe / share-sheet PWA) and the WireGuard/Headscale rollout for beyond-the-LAN — the endpoint itself needs zero code change for that.