docs: replace PLAN.md with README, add CLAUDE.md, DEVELOPMENT.md, TODO

PLAN.md (AI requirements doc) converted to README.md (human-facing
project overview with feature status table). CLAUDE.md added for
Claude Code with commands, architecture, and key conventions.
DEVELOPMENT.md covers first-time setup, per-component build commands,
hot-reload guidance, and ADB bundling notes. TODO.md tracks
implementation status across all phases.

CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development (full app)
+```bash
+bash scripts/dev.sh
+```
+Builds backend, desktop, regenerates Wails bindings, type-checks frontend, then starts `wails dev` with hot reload.
+
+### Build for production
+```bash
+bash scripts/build.sh
+```
+
+### Per-component build/check
+```bash
+# Backend
+cd backend-go && go build ./...
+
+# Desktop (Go)
+cd desktop && go build ./...
+
+# Frontend type-check only
+cd frontend-react && npx tsc -b --noEmit
+
+# Frontend bundle (outputs to desktop/frontend/dist/)
+cd frontend-react && npm run build
+
+# Wails desktop binary
+cd desktop && export PATH="$PATH:$(go env GOPATH)/bin" && wails build
+
+# Android SDK
+cd android-sdk && ./gradlew :sdk:assembleDebug
+```
+
+### Regenerate Wails JS bindings
+```bash
+cd desktop && export PATH="$PATH:$(go env GOPATH)/bin" && wails generate module
+```
+Run this after adding or changing any exported method on `App` in `desktop/app.go`. Output goes to `frontend-react/src/wailsjs/` — do not edit those files manually.
+
+---
+
+## Architecture
+
+```
+Android App → Instrumentation SDK → ADB Tunnel → Go Backend → React Frontend → Wails Desktop Shell
+```
+
+### Monorepo layout
+
+| Directory | Module / Package | Role |
+|---|---|---|
+| `desktop/` | `git.achmad.dev/admin/droidscope/desktop` | Wails app — entry point, `app.go` exposes bound methods |
+| `backend-go/` | `git.achmad.dev/admin/droidscope/backend` | Go packages: ADB, device, logcat, network, storage, etc. |
+| `frontend-react/` | — | Vite + React + TypeScript UI |
+| `android-sdk/` | `dev.achmad.droidscope` | Kotlin instrumentation SDK |
+| `scripts/` | — | `dev.sh`, `build.sh`, `download-adb.sh` |
+
+### Go workspace
+`go.work` links `./desktop` and `./backend-go` for local resolution. `desktop/go.mod` also has a `replace` directive — both are needed (`go.work` for IDE/build, `replace` for `go mod tidy`).
+
+### Wails ↔ React bridge
+- `desktop/wails.json`: `"frontend:dir": "../frontend-react"`, `"wailsjsdir": "../frontend-react/src"`
+- Vite `build.outDir` is `../desktop/frontend/dist` so Go's `//go:embed` works
+- Import bound methods from `@/wailsjs/go/main/App` in React
+
+### State model (frontend)
+- **`selectedDeviceId`** — which device the info panel is showing (can be anything)
+- **`profiledDeviceId`** — the active monitoring target for all feature panels (logcat, network, etc.)
+- These are separate concepts in `app-store.ts` (Zustand)
+
+### Active device scoping (all feature panels)
+Every feature panel outside Device Management must:
+1. Import `useActiveDevice` from `@/hooks/use-active-device`
+2. Gate all polling/streaming behind `isMonitoring`
+3. Store per-device data via `patchDeviceCache(deviceId, data)` — never cleared on device switch
+4. Render `<NoDeviceSelected />` when `!isMonitoring`
+
+### ADB binary resolution (runtime)
+`desktop/internal/adbembed/` — resolves in order: embedded binary → `$ANDROID_HOME/platform-tools/adb` → `adb` on `$PATH`. Embed directive uses `//go:embed all:bin` (not `//go:embed bin`) because the placeholder file is hidden.
+
+### Static vs live device data
+- `GetDeviceInfo(deviceId)` — one-time fetch, ~20 static fields (model, OS version, ABI, etc.)
+- `GetDeviceLiveStats(deviceId)` — polled every 1 s (RAM, battery, thermal, storage, IP)
+- `devices:changed` Wails event — emitted every 1 s for the device list
+
+---
+
+## Key conventions
+
+- Never use `namespace` TypeScript syntax — it conflicts with Wails-generated `models.ts` and `erasableSyntaxOnly` must stay off in `tsconfig.app.json`
+- shadcn/ui uses Base UI (not Radix UI) — `DialogTrigger` has no `asChild` prop; use controlled `open` state instead
+- `tsconfig.app.json` has no `baseUrl`; path alias `@/*` → `./src/*` works via `moduleResolution: bundler`
+- Do not run `go work sync` — it fails for unpublished modules; the workspace + replace approach handles everything
+- Never commit anything under `frontend-react/src/wailsjs/` — it is auto-generated

DEVELOPMENT.md

@@ -0,0 +1,237 @@
+# DroidScope — Development Guide
+
+## Prerequisites
+
+| Tool | Version | Install |
+|---|---|---|
+| Go | 1.23+ | https://go.dev/dl |
+| Node.js | 20+ | https://nodejs.org |
+| Wails CLI | v2 | `go install github.com/wailsapp/wails/v2/cmd/wails@latest` |
+| Git | any | — |
+
+> **macOS only:** Wails requires Xcode Command Line Tools — `xcode-select --install`
+>
+> **Linux only:** Wails requires `libgtk-3-dev libwebkit2gtk-4.0-dev` (Debian/Ubuntu) or equivalent.
+>
+> **Windows only:** Wails requires WebView2 (ships with Windows 11, otherwise install from Microsoft).
+
+---
+
+## First-time Setup
+
+```bash
+# 1. Install frontend dependencies
+cd frontend-react
+npm install
+
+# 2. (Optional) Download bundled ADB binaries for distribution builds
+# Skip this for local dev — the app falls back to your system ADB
+bash scripts/download-adb.sh
+
+# 3. Make sure your system ADB is accessible for local dev
+# Either via ANDROID_HOME or PATH:
+export ANDROID_HOME=~/Library/Android/sdk   # macOS example
+# or: ensure `adb` is on your PATH
+```
+
+---
+
+## Running in Development
+
+```bash
+bash scripts/dev.sh
+```
+
+**What `dev.sh` does, in order:**
+
+| Step | Command | What it checks |
+|---|---|---|
+| 1 | `go build ./...` in `backend-go/` | Backend packages compile without errors |
+| 2 | `go build ./...` in `desktop/` | Desktop Go code (app.go, main.go, embeds) compiles |
+| 3 | `wails generate module` in `desktop/` | Regenerates `frontend-react/src/wailsjs/` from current `app.go` bindings |
+| 4 | `npm install` + `tsc -b --noEmit` in `frontend-react/` | Installs any new deps, type-checks TypeScript |
+| — | `wails dev` in `desktop/` | Starts the desktop app with hot reload |
+
+If any step fails the script exits immediately (due to `set -e`) — fix the error and re-run.
+
+**What happens once running:**
+- Wails compiles the Go backend and opens a native desktop window
+- Wails starts the Vite dev server (`npm run dev` in `frontend-react/`)
+- React/TS changes hot-reload instantly without restarting
+- Go changes (in `app.go`, `backend-go/`) require re-running `dev.sh`
+
+> **When to re-run `dev.sh` vs just saving a file:**
+> - Edited only `.tsx` / `.ts` / `.css` → Vite hot-reloads automatically, no restart needed
+> - Edited `app.go` (added/changed a bound method) → re-run `dev.sh` to rebuild Go + regenerate bindings
+> - Edited anything under `backend-go/` → re-run `dev.sh` to rebuild
+
+**Frontend only** (browser preview, no Wails bindings):
+
+```bash
+cd frontend-react
+npm run dev
+# → http://localhost:5173
+```
+
+> Wails bindings (`ListDevices`, `GetDeviceInfo`, etc.) are no-ops in plain browser mode — they only work inside the Wails desktop window.
+
+---
+
+## Building for Production
+
+### Full desktop app (recommended)
+
+```bash
+bash scripts/build.sh
+```
+
+Or manually:
+
+```bash
+# Step 1 — build frontend (outputs to desktop/frontend/dist/)
+cd frontend-react
+npm run build
+
+# Step 2 — build desktop binary (embeds frontend dist + ADB binaries)
+cd desktop
+export PATH="$PATH:$(go env GOPATH)/bin"
+wails build
+```
+
+Output: `desktop/build/bin/DroidScope` (macOS/Linux) or `desktop/build/bin/DroidScope.exe` (Windows)
+
+---
+
+### Backend only
+
+```bash
+cd backend-go
+go build ./...
+```
+
+---
+
+### Frontend only (static bundle)
+
+```bash
+cd frontend-react
+npm run build
+# Output: desktop/frontend/dist/
+```
+
+---
+
+### Android SDK
+
+```bash
+cd android-sdk
+./gradlew :sdk:assembleDebug     # debug AAR
+./gradlew :sdk:assembleRelease   # release AAR
+# Output: android-sdk/sdk/build/outputs/aar/
+```
+
+---
+
+## Type Checking (no build)
+
+```bash
+# TypeScript
+cd frontend-react
+npx tsc -b --noEmit
+
+# Go
+cd backend-go && go build ./...
+cd desktop && go build ./...
+```
+
+---
+
+## Regenerating Wails JS Bindings
+
+Run this after adding or changing any exported method on `App` in `desktop/app.go`:
+
+```bash
+cd desktop
+export PATH="$PATH:$(go env GOPATH)/bin"
+wails generate module
+# Output: frontend-react/src/wailsjs/
+```
+
+---
+
+## Project Structure
+
+```
+DroidScope/
+├── desktop/                    ← Wails app (Go entry point)
+│   ├── app.go                  ← Wails-bound methods (called from frontend)
+│   ├── main.go                 ← App bootstrap
+│   ├── wails.json              ← Wails config (frontend dir, dev server)
+│   └── internal/adbembed/      ← ADB binary embedding + runtime extraction
+│
+├── backend-go/                 ← Go backend packages
+│   ├── adb/                    ← ADB command wrapper
+│   ├── device/                 ← Device manager + DeviceInfo fetcher
+│   ├── logcat/                 ← (stub) Logcat streaming
+│   ├── network/                ← (stub) Network inspector
+│   ├── storage/                ← (stub) SharedPrefs, SQLite, files
+│   ├── runtime/                ← (stub) Runtime config override
+│   ├── session/                ← (stub) Session management
+│   └── protocol/               ← Shared event types (Go structs)
+│
+├── frontend-react/             ← Vite + React + TypeScript
+│   ├── src/
+│   │   ├── wailsjs/            ← Auto-generated Wails bindings (do not edit)
+│   │   ├── features/           ← Feature modules (devices, logcat, network…)
+│   │   ├── components/         ← Shared UI components (layout, shadcn/ui)
+│   │   ├── hooks/              ← Shared hooks (useActiveDevice)
+│   │   ├── store/              ← Zustand global state
+│   │   └── types/              ← Shared TypeScript types (protocol)
+│   └── vite.config.ts          ← Build outputs to ../desktop/frontend/dist/
+│
+├── android-sdk/                ← Kotlin Android SDK (Gradle)
+│   └── sdk/src/main/kotlin/dev/achmad/droidscope/
+│
+├── scripts/
+│   ├── dev.sh                  ← Start full dev environment
+│   ├── build.sh                ← Production build
+│   └── download-adb.sh         ← Download ADB binaries for bundling
+│
+├── go.work                     ← Go workspace (links desktop + backend-go)
+├── README.md                   ← Project overview and feature roadmap
+├── TODO.md                     ← Implementation status
+└── DEVELOPMENT.md              ← This file
+```
+
+---
+
+## Key Conventions
+
+### Adding a new Go method callable from the frontend
+
+1. Add the method to `desktop/app.go` (must be exported, receiver `*App`)
+2. Run `wails generate module` from `desktop/`
+3. Import from `@/wailsjs/go/main/App` in React
+
+### Adding a new backend-go package
+
+1. Create the package under `backend-go/`
+2. The `go.work` workspace + `replace` directive in `desktop/go.mod` handle local resolution — no publishing needed
+
+### Active device scoping (all features)
+
+- Import `useActiveDevice` from `@/hooks/use-active-device`
+- Check `isMonitoring` before starting streams or polls
+- Store per-device data in `deviceCache` via `patchDeviceCache(deviceId, data)` — never cleared on device switch
+- Show `<NoDeviceSelected />` when `!isMonitoring`
+
+---
+
+## ADB Binary Bundling
+
+For **local development** the app resolves ADB in this order:
+1. Embedded binary in `desktop/internal/adbembed/bin/` (empty until `download-adb.sh` is run)
+2. `$ANDROID_HOME/platform-tools/adb`
+3. `adb` on `$PATH`
+
+For **distribution builds** run `scripts/download-adb.sh` once before `wails build` to embed ADB for all platforms.

PLAN.md

@@ -1,760 +0,0 @@
-# Android Observability Platform — AI-Oriented Requirements Document
-
-## Project Name
-
-Temporary codename:
-- DroidScope
-
----
-
-# Project Summary
-
-A standalone cross-platform desktop application for Android application observability and debugging.
-
-The platform allows developers to:
-
-- Connect Android devices/emulators through ADB
-- Monitor application behavior in real time
-- Inspect network traffic
-- Inspect storage and databases
-- Monitor performance metrics
-- Analyze memory behavior
-- Observe Jetpack Compose recompositions
-- Stream logs
-- Modify runtime configurations
-
-The application must provide a modern browser-like developer tooling experience similar to Chrome DevTools.
-
----
-
-# Primary Goals
-
-## Functional Goals
-
-- Real-time Android observability
-- Cross-platform desktop support
-- Multi-device support
-- Low-overhead instrumentation
-- Developer-focused workflows
-- Unified debugging interface
-- Plugin-capable architecture
-
----
-
-# Technology Stack
-
-## Desktop Framework
-
-### Wails
-
-Responsibilities:
-- Native desktop shell
-- Window management
-- Packaging
-- Native integrations
-
----
-
-## Backend
-
-### Go
-
-Responsibilities:
-- ADB communication
-- Device management
-- Event streaming
-- Monitoring orchestration
-- Local APIs
-- Session management
-- Data aggregation
-
----
-
-## Frontend
-
-### React + TypeScript
-
-Responsibilities:
-- Dashboard UI
-- Inspector panels
-- Charts
-- Tables
-- Interaction layer
-
----
-
-# High-Level Architecture
-
-```text
-Android App
-    ↓
-Instrumentation SDK
-    ↓
-ADB Tunnel / WebSocket
-    ↓
-Go Backend
-    ↓
-React Frontend
-    ↓
-Wails Desktop Shell
-```
-
----
-
-# Repository Structure
-
-```text
-root/
-├── desktop/
-├── backend-go/
-├── frontend-react/
-├── android-sdk/
-├── shared-protocol/
-├── docs/
-└── scripts/
-```
-
----
-
-# Core Components
-
-# 1. Android Instrumentation SDK
-
-## Description
-
-Embedded Android SDK responsible for collecting runtime diagnostics and streaming events to the desktop application.
-
----
-
-## SDK Requirements
-
-### General
-
-- Kotlin-first
-- Android SDK 24+
-- Modular architecture
-- Debug-build focused
-- Runtime enable/disable
-- Minimal overhead
-- Safe fallback behavior
-- R8/ProGuard compatibility
-
----
-
-# 2. Go Backend
-
-## Description
-
-Central orchestration engine responsible for:
-- ADB communication
-- Session handling
-- Event aggregation
-- WebSocket streaming
-- Data persistence
-
----
-
-## Backend Requirements
-
-### Device Management
-
-#### Capabilities
-
-- Detect connected devices
-- Support multiple devices
-- Wireless ADB support
-- Device reconnect handling
-- Emulator support
-
-#### Commands
-
-- List devices
-- Connect device
-- Disconnect device
-- Restart session
-
----
-
-### Event Streaming
-
-#### Requirements
-
-- WebSocket-based streaming
-- Low latency
-- Event batching
-- Backpressure handling
-- Event replay support
-
----
-
-### Session Management
-
-#### Requirements
-
-- Multiple concurrent sessions
-- Persistent sessions
-- Session restore
-- Session metadata
-
----
-
-### Security
-
-#### Requirements
-
-- Local-only communication by default
-- Session isolation
-- Optional authentication
-- Safe runtime permissions
-
----
-
-# 3. React Frontend
-
-## Description
-
-Primary user interface for observability and inspection.
-
----
-
-## Frontend Requirements
-
-### General
-
-- Modern desktop UI
-- Responsive layout
-- Fast rendering
-- Keyboard shortcuts
-- Search everywhere
-- Virtualized large lists
-- Multi-tab support
-
----
-
-# Feature Requirements
-
-# Device Manager
-
-## Requirements
-
-### Device List
-
-Display:
-- Device name
-- Device ID
-- Android version
-- Connection type
-- Connection status
-- Battery level
-- CPU architecture
-
----
-
-### Device Actions
-
-Support:
-- Connect
-- Disconnect
-- Refresh
-- Restart session
-- Open shell
-
----
-
-# Logcat Monitoring
-
-## Requirements
-
-### Features
-
-- Real-time log streaming
-- Structured log rendering
-- Tag filtering
-- Priority filtering
-- Search
-- Export logs
-
-### Supported Priorities
-
-- Verbose
-- Debug
-- Info
-- Warn
-- Error
-- Assert
-
----
-
-# Network Inspector
-
-## Requirements
-
-### Capture
-
-- HTTP
-- HTTPS
-- WebSocket traffic
-
----
-
-### Request Inspection
-
-Display:
-- URL
-- Method
-- Headers
-- Query parameters
-- Timing
-- Body
-
----
-
-### Response Inspection
-
-Display:
-- Status code
-- Headers
-- Body
-- Response size
-- Timing
-
----
-
-### Features
-
-- JSON formatting
-- CURL export
-- Request replay
-- Filtering
-- Search
-- Timeline view
-
----
-
-# Shared Preferences Inspector
-
-## Requirements
-
-### Features
-
-- View entries
-- Edit entries
-- Delete entries
-- Live updates
-
-### Data Types
-
-- String
-- Int
-- Long
-- Float
-- Boolean
-- String Set
-
----
-
-# Database Browser
-
-## Requirements
-
-### Features
-
-- SQLite browsing
-- Room database support
-- Table inspection
-- Query execution
-- Schema visualization
-
-### Query Support
-
-- Read-only queries initially
-- Query history
-- Export support
-
----
-
-# File Browser
-
-## Requirements
-
-### Features
-
-- Browse sandbox files
-- Download files
-- Upload files
-- Delete files
-- Preview files
-
-### Preview Support
-
-- Text
-- JSON
-- Images
-
----
-
-# Runtime Configuration
-
-## Requirements
-
-### Features
-
-- Base URL override
-- Feature flag toggles
-- Runtime config editing
-- Deep link launcher
-
----
-
-# FPS Monitoring
-
-## Requirements
-
-### Features
-
-- Real-time FPS tracking
-- Jank detection
-- Slow frame tracking
-- Frame drop statistics
-
----
-
-# Memory Monitoring
-
-## Requirements
-
-### Features
-
-- Heap usage tracking
-- Allocation monitoring
-- GC event tracking
-- Native memory visibility
-
----
-
-# Memory Leak Detection
-
-## Requirements
-
-### Features
-
-- Activity leak detection
-- Fragment leak detection
-- Retained object tracking
-- Leak history
-
----
-
-# Thread Monitoring
-
-## Requirements
-
-### Features
-
-- Active thread list
-- Main-thread blocking detection
-- Thread state visibility
-- ANR risk visibility
-
----
-
-# StrictMode Monitoring
-
-## Requirements
-
-### Features
-
-- Disk read violations
-- Disk write violations
-- Network-on-main-thread detection
-- Resource leak detection
-
----
-
-# Compose Recomposition Monitoring
-
-## Requirements
-
-### Features
-
-- Recomposition counts
-- Hotspot detection
-- Frequent recomposition visibility
-- State update tracing
-
----
-
-# WebView Monitoring
-
-## Requirements
-
-### Features
-
-- URL tracking
-- Console log inspection
-- Resource loading visibility
-- WebView lifecycle visibility
-
----
-
-# Device Information
-
-## Requirements
-
-### Display
-
-- Device manufacturer
-- Device model
-- Android version
-- ABI
-- RAM
-- Storage
-- Battery
-- Thermal status
-
----
-
-# Loaded Libraries Inspection
-
-## Requirements
-
-### Features
-
-- Loaded native libraries
-- Dynamic library visibility
-- ABI metadata
-
----
-
-# Secure Storage Inspection
-
-## Requirements
-
-### Features
-
-- Keystore visibility
-- Key alias visibility
-- Encryption metadata visibility
-
----
-
-# Dashboard Layout
-
-# Main Sections
-
-## Sidebar
-
-Contains:
-- Devices
-- Overview
-- Logs
-- Network
-- Storage
-- Performance
-- Compose
-- WebView
-- Runtime
-- Settings
-
----
-
-## Main Panel
-
-Displays:
-- Active inspector
-- Charts
-- Tables
-- Request details
-- Device information
-
----
-
-# Non-Functional Requirements
-
-# Performance
-
-## Requirements
-
-- Low memory overhead
-- Low CPU overhead
-- Virtualized rendering
-- Efficient event streaming
-
----
-
-# Reliability
-
-## Requirements
-
-- Graceful reconnect handling
-- Crash recovery
-- Offline handling
-- Buffered events
-
----
-
-# Security
-
-## Requirements
-
-- Debug-only instrumentation by default
-- Sensitive data masking
-- Localhost-only communication by default
-
----
-
-# Packaging Requirements
-
-## Supported Platforms
-
-- macOS
-- Windows
-- Linux
-
----
-
-## Packaging Goals
-
-- Single installer
-- Bundled ADB
-- No Android Studio requirement
-- Minimal setup
-
----
-
-# AI Agent Guidance
-
-# Backend Guidelines
-
-## Go Backend Principles
-
-- Use goroutines for stream handling
-- Prefer event-driven architecture
-- Avoid tightly coupled modules
-- Use interfaces for feature modules
-- Keep protocol versioned
-
----
-
-# Frontend Guidelines
-
-## React Principles
-
-- Use feature-based architecture
-- Avoid excessive global state
-- Use virtualization for large datasets
-- Prefer streaming updates over polling
-
----
-
-# Android SDK Guidelines
-
-## SDK Principles
-
-- Avoid blocking main thread
-- Ensure instrumentation can be disabled
-- Prefer lightweight hooks
-- Avoid unstable internal Android APIs where possible
-
----
-
-# Event Protocol
-
-## Event Structure
-
-All events should contain:
-
-```json
-{
-  "type": "",
-  "timestamp": 0,
-  "deviceId": "",
-  "sessionId": "",
-  "payload": {}
-}
-```
-
----
-
-# MVP Scope
-
-# Phase 1
-
-## Included Features
-
-- Device management
-- Logcat streaming
-- Network inspection
-- SharedPreferences inspection
-- SQLite browser
-- File browser
-- Runtime URL override
-
----
-
-# Phase 2
-
-## Included Features
-
-- FPS monitoring
-- Memory monitoring
-- StrictMode monitoring
-- Thread monitoring
-
----
-
-# Phase 3
-
-## Included Features
-
-- Leak visualization
-- Compose recomposition tooling
-- Advanced tracing
-- Flamegraphs
-
----
-
-# Future Scope
-
-## Potential Future Features
-
-- Plugin system
-- Scripting support
-- Automation support
-- iOS support
-- Flutter support
-- React Native support
-- Remote device support
-- Team collaboration
-
----
-
-# Out of Scope
-
-## Explicit Non-Goals
-
-- Production analytics platform
-- MDM solution
-- CI/CD tooling
-- Cloud-hosted observability platform
-- Crash reporting replacement
-
----
-
-# Success Criteria
-
-## MVP Success Conditions
-
-- Device detection works reliably
-- Logs stream in real time
-- Network inspector functions correctly
-- Storage inspection is stable
-- Dashboard remains responsive under heavy streams
-
----
-
-# Product Positioning
-
-Primary positioning statement:
-
-> Chrome DevTools for Android Native Apps

README.md

@@ -0,0 +1,114 @@
+# DroidScope
+
+> Chrome DevTools for Android Native Apps
+
+A standalone cross-platform desktop application for Android application observability and debugging. Connect any Android device or emulator and get real-time visibility into logs, network traffic, storage, performance, and more — without needing Android Studio.
+
+---
+
+## Features
+
+### Phase 1 — MVP
+| Feature | Status |
+|---|---|
+| Device management (USB + wireless ADB) | ✅ Done |
+| Real-time device stats (RAM, battery, thermal, storage) | ✅ Done |
+| Logcat streaming | 🔧 In progress |
+| Network inspector (OkHttp interceptor) | 📋 Planned |
+| SharedPreferences inspector | 📋 Planned |
+| SQLite browser | 📋 Planned |
+| File browser | 📋 Planned |
+| Runtime URL override & feature flags | 📋 Planned |
+
+### Phase 2
+FPS monitoring, memory monitoring, StrictMode violations, thread monitoring / ANR risk.
+
+### Phase 3
+Memory leak detection, Jetpack Compose recomposition tooling, advanced tracing, flamegraphs.
+
+---
+
+## Technology Stack
+
+| Layer | Technology |
+|---|---|
+| Desktop shell | [Wails v2](https://wails.io) |
+| Backend | Go 1.23+ |
+| Frontend | React + TypeScript + Vite |
+| Android SDK | Kotlin, minSdk 24 |
+| UI components | shadcn/ui + Tailwind CSS |
+| State | Zustand |
+| Data fetching | TanStack Query |
+
+---
+
+## Architecture
+
+```
+Android App
+    ↓
+DroidScope Instrumentation SDK  (android-sdk/)
+    ↓
+ADB tunnel / WebSocket
+    ↓
+Go backend  (backend-go/)
+    ↓
+React frontend  (frontend-react/)
+    ↓
+Wails desktop shell  (desktop/)
+```
+
+The desktop app bundles the Go backend and React UI into a single native binary. No server required — everything runs locally.
+
+---
+
+## Repository Structure
+
+```
+DroidScope/
+├── desktop/          — Wails app (Go entry point, app.go bindings)
+├── backend-go/       — Go packages: ADB, device, logcat, network, storage…
+├── frontend-react/   — Vite + React + TypeScript UI
+├── android-sdk/      — Kotlin instrumentation SDK
+├── scripts/          — dev.sh, build.sh, download-adb.sh
+├── go.work           — Go workspace
+├── DEVELOPMENT.md    — Full development guide
+└── TODO.md           — Implementation status
+```
+
+---
+
+## Getting Started
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for full setup instructions.
+
+**Quick start:**
+
+```bash
+# 1. Install frontend dependencies
+cd frontend-react && npm install
+
+# 2. Start full dev environment
+bash scripts/dev.sh
+```
+
+Prerequisites: Go 1.23+, Node.js 20+, Wails CLI v2, system ADB accessible via `$ANDROID_HOME` or `$PATH`.
+
+---
+
+## Design Principles
+
+- **Local-only by default** — all communication stays on localhost; no cloud dependency
+- **Debug-build focused** — instrumentation SDK is designed for development builds, not production
+- **Low overhead** — minimal CPU/memory impact on both desktop and device
+- **Multi-device** — supports monitoring multiple connected devices simultaneously
+- **Retained data** — switching between devices preserves previously captured data in memory
+
+---
+
+## Out of Scope
+
+- Production analytics / crash reporting
+- MDM / device management
+- Cloud-hosted observability
+- CI/CD tooling

TODO.md

@@ -0,0 +1,148 @@
+# DroidScope — TODO
+
+## Legend
+- `[x]` Done
+- `[ ]` Not started
+- `[~]` In progress
+
+---
+
+## Infrastructure
+
+- [x] Project scaffold (Wails + Go + React/TS + Kotlin SDK)
+- [x] Monorepo structure (`desktop/`, `backend-go/`, `frontend-react/`, `android-sdk/`)
+- [x] Go workspace (`go.work`)
+- [x] Shared event protocol (Go structs + TypeScript types)
+- [x] Dev script (`scripts/dev.sh`) — builds backend, desktop, regenerates bindings, type-checks, then starts
+- [x] Build script (`scripts/build.sh`)
+- [x] Development guide (`DEVELOPMENT.md`)
+- [x] Bundle ADB binary infrastructure (`desktop/internal/adbembed/`)
+- [x] ADB discovery at runtime (embedded → ANDROID_HOME → PATH fallback)
+- [x] Download ADB binaries for distribution (`scripts/download-adb.sh` ready, run once)
+- [ ] CI/CD pipeline
+
+---
+
+## Phase 1 — MVP
+
+### Device Management
+- [x] ADB wrapper (`backend-go/adb/`)
+- [x] List connected devices (1s poll)
+- [x] Device connect / disconnect
+- [x] Wireless ADB support
+- [x] Device reconnect handling
+- [x] Emulator support
+- [x] Static device info (model, Android version, ABI, manufacturer, screen, build fingerprint)
+- [x] Live device stats — 1s poll (available RAM, battery level/status, thermal status, available storage, IP)
+- [x] Frontend: device list panel with real-time updates
+- [x] Frontend: wireless connect dialog
+- [x] Frontend: disconnect action
+- [x] Frontend: device info panel — static fields fetched once, live fields pulsing every second
+- [x] Frontend: RAM usage progress bar (live)
+- [x] Frontend: split layout — device list + info detail side by side
+- [x] Frontend: selected device (info view) vs profiled device (monitoring target) — separate concepts
+- [x] Frontend: Profile / Stop profiling toggle per device card
+- [x] Frontend: active profiling indicator bar in device list
+- [x] Frontend: auto-clear selected + profiled device when device disconnects or goes offline
+
+### Logcat
+- [~] Backend stub (`backend-go/logcat/stream.go`)
+- [ ] Real-time logcat streaming via ADB
+- [ ] Structured log parsing (priority, tag, PID, message)
+- [ ] Wails event push to frontend
+- [ ] Frontend: log table with virtualized rendering
+- [ ] Frontend: filter by tag
+- [ ] Frontend: filter by priority (V/D/I/W/E/A)
+- [ ] Frontend: search
+- [ ] Frontend: export logs
+
+### Network Inspector
+- [ ] Android SDK: OkHttp interceptor
+- [ ] Backend: receive + store network events
+- [ ] Frontend: request list
+- [ ] Frontend: request detail (headers, body, timing)
+- [ ] Frontend: response detail (status, headers, body, size)
+- [ ] Frontend: JSON formatting
+- [ ] Frontend: cURL export
+- [ ] Frontend: filter / search
+
+### Shared Preferences Inspector
+- [ ] Backend: pull + parse SharedPreferences XML via ADB
+- [ ] Backend: write-back support
+- [ ] Frontend: key/value table
+- [ ] Frontend: inline editing (String, Int, Long, Float, Boolean, StringSet)
+- [ ] Frontend: live update polling
+
+### SQLite Browser
+- [ ] Backend: pull database file via ADB
+- [ ] Backend: query execution
+- [ ] Frontend: table list
+- [ ] Frontend: table data viewer (paginated)
+- [ ] Frontend: SQL query editor
+- [ ] Frontend: query history
+- [ ] Frontend: export
+
+### File Browser
+- [ ] Backend: `adb shell ls` traversal
+- [ ] Backend: file download (`adb pull`)
+- [ ] Backend: file upload (`adb push`)
+- [ ] Backend: file delete
+- [ ] Frontend: file tree / list
+- [ ] Frontend: text / JSON / image preview
+
+### Runtime Configuration
+- [ ] Android SDK: base URL override hook
+- [ ] Android SDK: feature flag toggle
+- [ ] Backend: send config command to device
+- [ ] Frontend: URL override input
+- [ ] Frontend: feature flag toggles
+- [ ] Frontend: deep link launcher
+
+---
+
+## Phase 2
+
+- [ ] FPS monitoring (backend + frontend chart)
+- [ ] Memory monitoring (heap, GC events)
+- [ ] StrictMode violation monitoring
+- [ ] Thread monitoring + ANR risk
+
+---
+
+## Phase 3
+
+- [ ] Memory leak detection (Activity/Fragment)
+- [ ] Compose recomposition tooling
+- [ ] Advanced tracing
+- [ ] Flamegraphs
+
+---
+
+## Android SDK
+
+- [x] Project skeleton (`android-sdk/`)
+- [x] `DroidScope.init()` / `shutdown()` entry point
+- [ ] WebSocket transport to desktop
+- [ ] Network interceptor (OkHttp)
+- [ ] SharedPreferences observer
+- [ ] Logcat forwarder (SDK-side filtering)
+- [ ] FPS collector (Choreographer)
+- [ ] Memory collector (Debug.MemoryInfo)
+- [ ] StrictMode collector
+- [ ] Compose recomposition collector
+
+---
+
+## Frontend Shell
+
+- [x] Sidebar navigation
+- [x] Dark theme
+- [x] Selected device vs profiled device — two independent concepts in store
+- [x] `useActiveDevice` hook — reads `profiledDeviceId`; `isMonitoring = false` pauses all feature panels
+- [x] `NoDeviceSelected` shared component — guides user to Profile a device
+- [x] Per-device data cache (`deviceCache`) — retained on device switch, never cleared automatically
+- [ ] Persistent profiled device indicator in sidebar or top bar
+- [ ] Multi-tab panel support
+- [ ] Keyboard shortcuts
+- [ ] Global search
+- [ ] Settings page