vpnhide/docs

vpnhide documentation

Docs here are split by audience. Pick the row that matches what you're doing.

For users — the offline guide

End-user documentation lives in help/ as localized Markdown (EN/RU/ZH). This is the single source: the same articles are synced into the app (Settings → Help & guide) and browsable here on GitHub. Start at the guide index.

Covers install, choosing and installing a native backend, setting up hiding, understanding the self-test results, statistics, updating/back-up/removal, limits, and a glossary. The project README is the short entry point that links into it.

For contributors — architecture & reference

Stable references for anyone changing the code. Read the relevant one before a PR.

Doc	What it covers
development.md	Prereqs, per-module build quickstart, device install, CI lints
protocol.md	The frozen control/telemetry wire between activator, app and backends
storage.md	Storage & activation design: the JSON canonical, the activator, SELinux
state.md	Every persistent path / proc entry / iptables chain the project touches
threat-model.md	Attacker capabilities, trusted components, security boundaries and limits of hiding/diagnostic claims
detection-vectors.md	What an app can probe and which component covers each vector
diagnostics.md	How the app self-tests hiding and attributes the result
debug-bundle.md	How to read a user's vpnhide_debug_*.zip bundle
limits.md	Every target/config/stats capacity ceiling and what binds first
lsposed-hook-debugging.md	Diagnosing why a Java-layer hook didn't attach on a ROM
adb-root-debugging.md	Making adb shell su useful on KernelSU/APatch/Magisk test devices
avd-magisk-testing.md	Testing on a rooted x86_64 AVD (Magisk + Zygisk + LSPosed)
changelog.md	Changelog storage (changelog.d/ fragments) and scripts/changelog.py
releasing.md	scripts/release.py usage and the version-bump flow
config-coordinator.md	How app configuration writes are owned: the process-owned coordinator, typed edits, drafts, phase outcomes and recovery
observation-coordinator.md	How root/app observations are read, invalidated, joined and quarantined; Dashboard/diagnostics refresh rules
root-mutation-transport.md	The vhhelper mutation supervisor: receipts, sessions, late-launch fencing and the isolated device fixture

Module-specific developer docs live next to their code: kmod/BUILDING.md, kmod/kpm/README.md, builtin/README.md (the in-tree kernel backend), lsposed/AGENTS.md, and each module's README.md. Repo conventions and the PR/changelog process are in CONTRIBUTING.md and AGENTS.md.

Roadmap, plans & working notes

Forward-looking, non-reference material — directions, plans and TODOs that aren't a release commitment — lives in notes/:

• notes/ROADMAP.md — larger product directions
• notes/setup-wizard-design.md — design proposal for the first-run setup wizard (not yet implemented)
• notes/app-state-transitions.md — the app state transition contract as implemented: machines, invariants, scenario traces, the recorded deviations and the known gaps
• notes/app-state-transitions-history.md — the stage-by-stage implementation log of that contract (§13–§22) with each stage's boundaries and validation
• notes/diagnostics-state-analysis.md — historical analysis of what "diagnostics" meant before the refactor and why
• notes/app-state-design.md — the original state redesign proposal (superseded by the contract)
• notes/ci-kernel-config-trim.md — the QEMU test-kernel trim: what it switches off and what it measures, the ABI guard that keeps it from moving a struct offset, and the options that look trimmable but are not
• notes/core-2.0-architecture.md — forward-looking design for a persistent root daemon replacing the per-call root helper: ownership, projection, auth and observer decisions
• notes/builtin-app-integration-audit.md — audit of how the app integrates the built-in kernel backend (picker, statistics, diagnostics, capture, reset)
• notes/ui-state-presentation-review.md — design review that led to the Situation classifier; decisions recorded, two since superseded
• notes/vpn-poll-device-validation.md — device acceptance evidence for the foreground app-VPN poller and the network callback lifecycle
• notes/release-candidates.md — TODO: vX.Y.Z-rc.N pre-release tags; what already works, what blocks it (versionCode scheme, release.py rotation, CI notes extraction)