docs: streamline README and split detailed guides

docs/development.md

@@ -0,0 +1,36 @@
+# Development and release verification
+
+## Requirements
+
+- Go 1.24 or newer
+- Linux
+- GNU `sha256sum`, `stat`, and `find`
+- `file`
+
+## Local verification
+
+```sh
+gofmt -w .
+go test ./...
+go vet ./...
+./scripts/check-docs.sh
+./scripts/test-hermetic.sh
+./scripts/test-release.sh
+./scripts/verify-clean-machine.sh
+```
+
+`test-hermetic.sh` runs the complete uncached Go suite as an unprivileged user and verifies that readable host configuration content and metadata remain unchanged.
+
+`verify-clean-machine.sh` uses isolated identity and XDG roots to exercise installation, Profile workflows, hermetic Target workflows, diagnostics, reset confirmation, Shell integration, and removal.
+
+## Release build
+
+```sh
+VERSION=v1.0.0 ./scripts/build-release.sh
+sha256sum -c dist/SHA256SUMS
+file dist/proxyctl-linux-amd64 dist/proxyctl-linux-arm64
+```
+
+The release consists of Linux amd64 and arm64 single binaries plus `SHA256SUMS`; it does not produce distribution packages or archives.
+
+`test-release.sh` builds twice, compares binaries and checksum manifests, validates both architectures and checksums, and verifies that process-test seams cannot enter a release artifact.

docs/security.md

@@ -0,0 +1,54 @@
+# Security and operational boundaries
+
+## Privileges
+
+User Targets normally require only access to user-owned files. APT and Docker daemon configuration generally require root authority.
+
+proxyctl never starts `sudo`, `pkexec`, or another elevation mechanism. Run `sudo proxyctl` explicitly when system Targets are needed. Under sudo, the invoking user remains the owner of Profiles, Shell integration, Docker client configuration, and GNOME settings; root authority is used for system Targets. A direct root login uses root as the owner.
+
+Docker daemon changes reload systemd and restart Docker immediately after confirmation.
+
+## Configuration recovery
+
+proxyctl prefers isolated, tool-owned overlays. Where shared configuration must be edited, it records the original value and a fingerprint of the last applied state.
+
+Restore and reset operations refuse to overwrite configuration that changed after proxyctl applied it. Recovery metadata must not be deleted before a successful reset.
+
+Use:
+
+```sh
+proxyctl doctor
+proxyctl reset
+proxyctl shell uninstall
+```
+
+Inspect and resolve all failures before removing the executable or state directory.
+
+## Credentials and privacy
+
+Proxy URLs may contain credentials. Profile, recovery, and managed credential-bearing files use restrictive permissions. Docker daemon configuration is owner-only while proxyctl manages credential-bearing proxy values.
+
+The TUI, diagnostics, errors, command output, and bounded local operation logs defensively redact credentials. Profile editor frames obscure URL user information. Credentials remain present in underlying configuration where a selected Target requires them, so host file security still matters.
+
+proxyctl has:
+
+- no telemetry
+- no automatic update checks
+- no automatic proxy-connectivity tests
+
+The user-initiated Protocol Probe contacts only the entered endpoint, performs protocol handshakes, and never forwards traffic through the proxy.
+
+## Scope
+
+proxyctl configures proxy settings; it does **not** manage or supervise proxy processes such as Clash, sing-box, or Xray. It does not manage subscriptions, nodes, latency, routing rules, transparent proxying, TUN/iptables/nftables, arbitrary services, or plugins.
+
+It currently excludes DNF, Git-specific settings, npm/pip settings, arbitrary systemd services, browser policies, KDE, Fish, Windows, macOS, distribution packages, mouse interaction, and cross-Target rollback.
+
+Support is limited to the Linux architectures and Targets documented in the README. When reporting an issue, include:
+
+- `proxyctl version`
+- redacted `proxyctl doctor` output
+- distribution and desktop/Shell details
+- affected Target and state
+
+Never include unredacted proxy credentials.

docs/user-guide.md

@@ -0,0 +1,75 @@
+# User guide
+
+## Profiles
+
+A Proxy Profile contains proxy URLs and bypass rules. The Active Profile is the source applied to every Enabled Target.
+
+Open Profile management with `m`:
+
+- `n`: create a Profile
+- `e` or Enter: edit the selected Profile
+- `d`: safely delete the selected Profile
+- Ctrl+S: save the editor
+- Ctrl+T: switch between Single and Advanced modes
+
+Single mode applies one URL to HTTP, HTTPS, and ALL/SOCKS. Advanced mode accepts separate values. A bare `host:port` is normalized to `http://`.
+
+Bypass entries may be comma- or newline-delimited hostnames, domain suffixes, IPv4/IPv6 addresses, or CIDR ranges. The editor normalizes and deduplicates valid entries.
+
+### Protocol Probe
+
+Press Ctrl+D while editing the Single proxy URL to run an explicit handshake probe. It reports HTTP and SOCKS5 support without forwarding traffic or contacting another endpoint.
+
+If both protocols are detected, the editor changes to Advanced mode and fills HTTP/HTTPS with `http://` and ALL/SOCKS with `socks5://`. GNOME cannot represent `socks5h` remote-DNS semantics; use Advanced mode with `socks5` when GNOME must use that endpoint.
+
+## Dashboard
+
+Press `p` to search and select the Active Profile. Select Targets with arrows or `j`/`k`; Space runs the contextual action:
+
+- **Enable** a Disabled Target
+- **Disable** an Enabled Target
+- **Apply Profile** to an External Target
+- **Resolve** a Drifted Target by reapplying the Active Profile or restoring the original configuration
+
+Restoration refuses to overwrite configuration that changed after proxyctl applied it.
+
+Other controls:
+
+- `r`: refresh detection
+- `u`: show unavailable Targets
+- Tab: switch between Target list and details
+- Page Up/Page Down: scroll details
+- `e`: expand or collapse the current error
+- `x`: acknowledge the current error
+- `?`: contextual Help
+- `q` or Esc: close the current page/dialog; `q` exits from the unobscured dashboard
+- Ctrl+C: request exit
+
+Conflicting actions are disabled while a mutation runs. Exit requests cancel cancellable work and wait for the operation to settle safely.
+
+## Target states
+
+- **Enabled:** managed configuration matches the Active Profile.
+- **Disabled:** no managed or positively recognized external proxy configuration was detected.
+- **External:** recognized proxy configuration exists outside proxyctl ownership.
+- **Drifted:** managed configuration no longer matches the Active Profile, including partial failures.
+
+External detection is best-effort. Disabled does not claim that every possible configuration source was exhaustively searched.
+
+## What each Target affects
+
+1. **Shell** — future commands in integrated Bash/Zsh sessions. It does not change existing processes or services.
+2. **APT** — persistent Debian-family package operations through a tool-owned `apt.conf.d` overlay.
+3. **Docker daemon** — registry and daemon traffic. Every change reloads systemd and restarts Docker.
+4. **Docker containers/builds** — proxy defaults for future containers and builds in the owning user's Docker client configuration. It does not configure the daemon.
+5. **GNOME** — compatible desktop applications using GNOME system proxy settings. It does not rewrite browser-specific profiles.
+
+## Responsive and accessible TUI
+
+At 100×28 and larger, Targets and details are side by side. At 60–99 columns they use one column. Below 60×16, proxyctl displays a minimum-size warning and restores interaction state after resize.
+
+Focus and state never rely on color alone. States include symbols and words such as `● Enabled`, `○ Disabled`, `◇ External`, `! Drifted`, and `… Checking`. No Nerd Font is required. Set `NO_COLOR` to disable color.
+
+Confirmation dialogs start on Cancel. The TUI uses the terminal alternate screen and restores the previous screen after exit.
+
+Profiles are normally stored at `~/.config/proxyctl/profiles.json` with owner-only permissions.