bradtraversy · bradtraversy · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -27,6 +27,9 @@ libc = "0.2"
 netstat2 = "0.11.2"
 sysinfo = "0.39.5"
 
+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem"] }
+
 # The profile that 'dist' will build with
 [profile.dist]
 inherits = "release"

diff --git a/README.md b/README.md
@@ -12,8 +12,8 @@ and what can be stopped safely.
 - **Port lookup** - type a port, see exactly what owns it and act on it
 - **Exposure labels** - know what is local-only, LAN-visible, or Docker-bound
 - **Stale hints** - find the dev server you forgot about last week
-- **Safe stop and restart** - graceful stop, verified relaunch, and force only
-  behind a second explicit yes
+- **Safe stop** - graceful stop first, with force only behind a second explicit
+  yes
 - **Docker and Advanced tabs** - container hints, raw sockets, JSON export
 
 Everything runs locally. No accounts, no telemetry.
@@ -44,20 +44,48 @@ Binaries and checksums for every platform are on the
 ## Use
 
 ```sh
-portdoc              # start the dashboard on 127.0.0.1:7788 and open it
-portdoc --port 7799  # different port
-portdoc --no-open    # don't open the browser
-portdoc --json       # print the snapshot as JSON and exit
+portdoc                    # choose foreground or background in a terminal
+portdoc foreground         # run attached to this terminal
+portdoc ui                 # foreground alias
+portdoc --port 7799        # use a different port
+portdoc --no-open          # don't open the browser
+portdoc --json             # print the snapshot as JSON and exit
 ```
 
 The server binds `127.0.0.1` only; nothing is reachable from the network.
-`Ctrl+C` stops it.
+Plain `portdoc` asks how to run only when launched in an interactive terminal.
+Scripts and other noninteractive launches preserve the foreground behavior
+without prompting. `Ctrl+C` stops a foreground server.
+
+### Background mode
+
+```sh
+portdoc background start             # install or refresh, then start now
+portdoc background status            # show manager and health status
+portdoc background stop              # stop now, keep sign-in startup enabled
+portdoc background disable           # stop and remove sign-in startup
+portdoc background start --port 7799 # manage a different port
+```
+
+Background mode uses the current user's native process manager and does not
+require administrator privileges:
+
+- Linux uses a systemd user service named `portdoc.service`.
+- macOS uses a LaunchAgent named `com.traversymedia.portdoc`.
+- Windows uses a Task Scheduler task named `PortDoc`.
+
+`background start` starts PortDoc immediately and enables it for future user
+sign-ins. It refuses to replace a foreground PortDoc or another application
+already using the requested port. `background stop` leaves sign-in startup
+configured, while `background disable` removes it.
 
 ## Known limitations (v0.1)
 
-- Restart requires an exact PID, executable, argument vector, and working
-  directory. PortDoc itself, Docker-managed services, and unknown owners cannot
-  be restarted.
+- Background mode on Linux requires systemd. It does not enable user lingering,
+  so PortDoc starts after sign-in rather than before it.
+- Installers do not yet coordinate upgrades with an already running background
+  instance. Stop it before upgrading, then run `portdoc background start` after
+  the upgrade.
 - Windows binaries are Authenticode-signed (as "Brad Traversy") since v0.1.1,
   so Smart App Control and SmartScreen accept them.
 - macOS binaries are unsigned; the installer and Homebrew paths avoid

diff --git a/blueprint/build-plan.md b/blueprint/build-plan.md
@@ -34,3 +34,7 @@
   - [x] 16b. **Project facts probe** - additive optional `ProjectGroup` fields (explicit contract decision): project description (package.json/Cargo.toml, README first line fallback), dev/build/start scripts, key deps, workspaces, node version, plus last commit age and dirty/clean from local git. Description renders inline in the Projects tab headers; full facts live in a project drawer (decided 2026-07-08: slide-over like the inspect drawer, no routing/detail page - the app has no router and the drawer pattern is established).
   - [x] 16c. **Project actions** - open in editor (new endpoint), copy cd command, and stop-all-services-in-project built on the feature 12 confirmation contract. Editor decided 2026-07-09: config `editor` key, `code` default. Shipped with two found-in-verification fixes: tilde expansion on `/api/open`/`/api/reveal`, stop-all dialog at App level.
 - [x] 17. **Signed Windows releases** - Authenticode-sign `portdoc.exe` in the release pipeline so Smart App Control and SmartScreen accept installs without overrides (v0.1.0 finding: SAC hard-blocks the unsigned binary on fresh Win11). Decided 2026-07-10: Azure Artifact Signing, Basic tier ($9.99/mo, 5k signatures), individual validation as "Brad Traversy". Integration is the proven unzip/sign/re-zip step on the Windows build leg (azure/artifact-signing-action@v2, OIDC login, RFC3161 timestamp) with `allow-dirty = ["ci"]`, swapped for cargo-dist's native `azure-windows-sign` when PR #2396 merges. Blocked on Brad's one-time Azure identity validation (1-20 business days); ships as v0.1.1. macOS signing/notarization deliberately deferred (curl/brew paths dodge Gatekeeper; needs the $99/yr Apple Developer membership and rcodesign - decide later).
+- [ ] 18. **Cross-platform run modes** - let users choose between an attached foreground server and a native per-user background process on Linux, macOS, and Windows, with safe lifecycle controls and upgrade handling.
+  - [ ] 18a. **Managed background runtime** - add explicit foreground and background lifecycle commands backed by a systemd user unit on Linux, a launchd LaunchAgent on macOS, and a per-user scheduled task on Windows. Background start runs PortDoc immediately and at future sign-ins.
+  - [ ] 18b. **Interactive launch choice** - make plain `portdoc` ask interactive terminal users whether to run in the foreground or background, handle already-running instances without a port fight, and keep managed and noninteractive invocations prompt-free. Implement this in the same feature branch as 18a so the work delivers the complete user-facing run-mode choice.
+  - [ ] 18c. **Safe background upgrades** - make the Linux, macOS, Windows, and Homebrew upgrade paths stop a managed PortDoc before replacing its binary, restore the prior background state after a successful update, and document recovery.