docs: harden agent-device skill security guidance (#113)

Author: thymikee

skills/agent-device/SKILL.md

@@ -108,16 +108,21 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - iOS settings helpers are simulator-only; use faceid `match|nonmatch|enroll|unenroll`.
 - If using `--save-script`, prefer explicit path syntax (`--save-script=flow.ad` or `./flow.ad`).
 
+## Security and Trust Notes
+
+- Prefer a preinstalled `agent-device` binary over on-demand package execution.
+- If install is required, pin an exact version (for example: `npx --yes agent-device@<exact-version> --help`).
+- Signing/provisioning environment variables are optional, sensitive, and only for iOS physical-device setup.
+- Logs/artifacts are written under `~/.agent-device`; replay scripts write to explicit paths you provide.
+- Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs.
+
 ## Common Mistakes
 
 - Mixing debug flow into normal runs (keep logs off unless debugging).
 - Continuing to use stale refs after screen transitions.
 - Using URL opens with Android `--activity` (unsupported combination).
 - Treating `boot` as default first step instead of fallback.
 
-If the CLI is not installed in environment, use:
-`npx -y agent-device`
-
 ## References
 
 - [references/snapshot-refs.md](references/snapshot-refs.md)

skills/agent-device/references/logs-and-debug.md

@@ -2,6 +2,22 @@
 
 Logging is off by default in normal flows. Enable it on demand for debugging windows. App output is written to a session-scoped file so agents can grep it instead of loading full logs into context.
 
+## Data Handling
+
+- Default app logs are stored under `~/.agent-device/sessions/<session>/app.log`.
+- Replay scripts saved with `--save-script` are written to the explicit path you provide.
+- Log files may contain sensitive runtime data; review before sharing and clean up when finished.
+- Use `AGENT_DEVICE_APP_LOG_REDACT_PATTERNS` to redact sensitive patterns at write time when needed.
+
+## Retention and Cleanup
+
+- Keep logging scoped to active debug windows (`logs clear --restart` before repro, `logs stop` after repro).
+- Prefer bounded inspection (`grep -n`, `tail -50`) instead of reading full logs into context.
+- Clear session logs when finished:
+  `agent-device logs clear`
+- Close session to stop background logging state:
+  `agent-device close`
+
 ## Quick Flow
 
 ```bash

skills/agent-device/references/permissions.md

@@ -13,6 +13,14 @@ Use Automatic Signing in Xcode, or provide optional overrides:
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
 
+Security guidance for these overrides:
+
+- These variables are optional and only needed for physical-device XCTest setup.
+- Treat values as sensitive host configuration; do not share in chat logs or commit to source control.
+- Do not provide private keys or unrelated secrets; use the minimum values required for signing.
+- Prefer Xcode Automatic Signing when possible to reduce manual secret/config handling.
+- For autonomous/CI runs, keep these unset by default and require explicit opt-in for physical-device workflows.
+
 If setup/build takes long, increase:
 
 - `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (default `45000`, for example `120000`)