Add managed state contract

docs/daemon-management.md

@@ -41,6 +41,7 @@ python3 -m ampg --config gateway.toml status
 python3 -m ampg --config gateway.toml doctor
 python3 -m ampg --config gateway.toml install-plan --profile mobile-i2p
 python3 -m ampg --config gateway.toml install-plan --profile mobile-i2p --write-artifacts
+python3 -m ampg --config gateway.toml state-contract --profile mobile-i2p
 python3 -m ampg --config gateway.toml addresses list --profile mobile-i2p
 python3 -m ampg --config gateway.toml addresses capture --profile mobile-i2p
 python3 -m ampg --config gateway.toml health-plan --profile mobile-i2p
@@ -69,6 +70,9 @@ Tor/I2P HTTP publishing, AMPG writes both transport-daemon artifacts and loopbac
 artifacts. The generated daemon configs store runtime state, identity keys, logs, and
 daemon-written addresses under `gateway.state_dir`.
 
+`state-contract` prints the resolved managed-state paths for enabled protocols, including
+which paths are AMPG-owned, daemon-written, required, or sensitive.
+
 `addresses list` prints the effective public address for each enabled protocol:
 configured, captured, derived, or placeholder. `addresses capture` reads daemon-written
 address files from AMPG state or a protocol `address_file` override, then updates the

docs/state-contract.md

@@ -0,0 +1,42 @@
+# State Contract
+
+> Status: draft | Updated 2026-07-06 | Applies to: managed daemon state
+
+AMPG keeps managed daemon state under `gateway.state_dir`. The state contract describes
+which files AMPG owns, which files daemons or adapters write, which paths may contain
+private keys, and which public address files `addresses capture` reads.
+
+## Command
+
+```sh
+python3 -m ampg --config gateway.toml state-contract
+python3 -m ampg --config gateway.toml state-contract --profile mobile-i2p
+python3 -m ampg --config gateway.toml state-contract --protocol tor
+```
+
+Each `AMPG_STATE` row includes:
+
+- `role`: state directory, daemon config, identity key, address file, log file, or similar.
+- `owner`: `ampg`, `daemon`, or `operator`.
+- `required`: whether a managed deployment expects the path.
+- `sensitive`: whether the path may contain private identity material.
+- `path`: resolved path under `gateway.state_dir` unless an adapter documents otherwise.
+
+## Address Capture
+
+`addresses capture` uses the same contract. For each enabled protocol it checks explicit
+`address_file` config first, then contract `address-file` entries in order.
+
+Current managed defaults:
+
+| Protocol | Preferred captured address file | Sensitive identity path |
+| --- | --- | --- |
+| Tor | `<state_dir>/<site>/tor/hidden-service/hostname` | `<state_dir>/<site>/tor/hidden-service` |
+| I2P | `<state_dir>/<site>/i2p/hostname.txt` | `<state_dir>/<site>/i2p/<keys_file>` |
+| Reticulum/IPFS/custom | `<state_dir>/<site>/<protocol>/address.txt` | adapter-specific |
+
+## Safety
+
+AMPG must never delete sensitive contract paths without an explicit destructive command.
+Live apply should copy reviewed config artifacts into their contract `daemon-config`
+paths, start daemons, capture public addresses, and then run published health checks.