# Whiteline Phone Agent (phonectl.dev)

> Open-Core BYO-Gateway autonomous Android controller over AccessibilityService, Dual MCP (`stdio` + Streamable HTTP `POST /mcp`), and compact `@e1..@eN` UI element refs with `screen_hash` optimistic locking. Zero root, zero ADB cable, zero embedded API keys or tokens.

## Core Endpoints & Artifacts

- [Full Agent Specification](https://phonectl.dev/llms-full.txt): Complete protocol guide, MCP tool schemas, `@e1..@eN` action loop, error codes (`STALE_SCREEN_HASH`, `FLAG_SECURE_PROTECTED`, `DEVICE_OFFLINE`), and BYO-Gateway setup.
- [OpenAPI 3.1 Schema](https://phonectl.dev/openapi.json): Machine-readable REST + MCP HTTP specification for Cloud Gateway v0.5.0.
- [MCP Discovery Manifest](https://phonectl.dev/.well-known/mcp.json): Dual transport descriptor (`https://mcp.phonectl.dev/mcp` Streamable HTTP and `whq-phone-mcp` stdio) listing all 6 MCP tools and 4 resources.
- [A2A Agent Card](https://phonectl.dev/.well-known/agent.json): Agent-to-Agent discovery metadata, Bearer auth declaration, and skill capabilities.
- [Portable Agent Skill](https://phonectl.dev/assets/agent/SKILL.md): Copy-ready MCP client setup for Claude Code, Codex, Cursor, and Antigravity.
- [Release Manifest (APK v0.4.0)](https://phonectl.dev/assets/downloads/release-manifest.json): Package metadata (`com.whiteline.controller`), Android 8.0+ (API 26) requirements, and SHA-256 checksum.
- [Download Zero-Secret APK v0.4.0](https://phonectl.dev/assets/downloads/whiteline-phone-agent-v0.4.0.apk): 13,532,155 bytes (`01f69caff000d209c548efc9f1e2756f5efcfa7e0989a02f5471ce6e7f69c3ed`).

## Architecture (Open-Core BYO-Gateway)

1. Each owner runs an isolated personal Cloud Gateway instance (Railway template or Python 3 container on `https://mcp.phonectl.dev`, or loopback `http://127.0.0.1:8765`).
2. The Android APK (`v0.4.0`) pairs in one tap via `whiteline://pair?url=<gateway_url>&token=<token>`, polls over HTTPS, exposes Accessibility UI trees + compressed JPEG viewports, and executes SafetyPolicyEngine-guarded gestures with a foreground Emergency Stop button.
3. AI coding agents connect via Streamable HTTP (`POST https://mcp.phonectl.dev/mcp` with `Authorization: Bearer <token>`) or local stdio (`whq-phone-mcp`), calling `phone_status`, `phone_observe`, `phone_act`, `phone_run`, `phone_apps`, and `phone_cancel`.

## Product Roadmap (v0.5.0 - v0.8.0)

- `v0.5.0` (Live Now): Custom domains (`phonectl.dev` + `mcp.phonectl.dev`), AEO discovery (`/llms.txt`, OpenAPI 3.1, `.well-known/*`, JSON-LD), Dual MCP server, deterministic `@e1..@eN` refs, `screen_hash` guard (`STALE_SCREEN_HASH`).
- `v0.6.0` (Next): Swarm reliability & HITL gate (`Idempotency-Key`, SQLite `Device Lease`, `semantic_ui_diff`, `AWAITING_APPROVAL` human confirmation for banking/destructive steps).
- `v0.7.0` (Planned): Zero-touch BYO-Gateway onboarding (1-Click Railway deploy + `/ui` QR generator, APK Readiness Checklist, on-device Per-App Privacy Allowlist/Denylist, signed APK releases).
- `v0.8.0` (Horizon): Bidirectional WebSocket transport (`150-300 ms`), Android clipboard & allowlisted OTP notification primitives, Intent/Deep-Link dispatch, `device_id` fleet routing, Direct LAN / Tailscale mode.