docs: update documentation to OKF v0.1 format

docs/guides/runtime-verification.md

@@ -0,0 +1,74 @@
+---
+type: guide
+title: Runtime Verification Guide
+description: Tester workflow for validating root cron startup, unprivileged bot execution, retry events, and persistent data behavior.
+tags: [guide, tester, docker, runtime]
+timestamp: 2026-08-04T20:44:00Z
+---
+
+# Setup
+
+1. Copy `.env.example` to `.env` and provide valid required values.
+2. Build and start the service:
+
+   ```bash
+   docker compose up --build -d
+   ```
+
+3. Follow container output:
+
+   ```bash
+   docker compose logs -f bot
+   ```
+
+# Expected Runtime Behavior
+
+The container remains running with `cron -f` as its foreground process. Startup output includes the configured `RUN_AT` and `TZ`. The scheduled cron command invokes `/usr/local/bin/run-bot.sh`, which runs the Python bot as user `bot`, not root.
+
+The host `./data` directory should contain the synchronized `blog/` clone and, after the state store is loaded, `posted.json`. Both are under the one `/app/data` mount.
+
+# Manual Run
+
+Run the same application command without waiting for cron:
+
+```bash
+docker compose exec bot /usr/local/bin/python -m tenbackward
+```
+
+A valid run exits `0`. A configuration failure exits `2`; an exhausted pipeline retry budget exits `1`.
+
+# Retry Checks
+
+To exercise transient failure handling, use a test repository or injected test double that fails once and then succeeds. Verify JSON events contain:
+
+| Event | Expected fields |
+|---|---|
+| `retry_attempt` | `operation`, `attempt`, and the original `error` text. |
+| `retry_exhausted` | Final `operation`, total `attempts`, and `error` text when all attempts fail. |
+| `run_complete` | Counters and `posted_ids` only after a successful pass. |
+
+With `MAX_RETRIES=0`, one attempt is still made and no sleep occurs. With a larger value, delays occur only between attempts and follow powers of two beginning at one second.
+
+# Configuration Checks
+
+Remove a required variable from `.env` and restart the service. The entrypoint should report the missing variable before cron starts. If the shell check is bypassed and the Python module runs directly, `configuration_error` should identify the missing key and return exit code `2` rather than silently substituting an application default.
+
+# Persistence and Failure Safety
+
+After a successful publication, inspect `/app/data/posted.json` and confirm new relative post paths appear under the `posted` list. If Mastodon publishing fails, the path must not be recorded; a later retry should be able to publish it again.
+
+# Key Visual/Observable Elements
+
+This service has no graphical UI. Test-facing outputs are:
+
+* Container status and `docker compose logs` output.
+* JSON-per-line startup, retry, failure, and completion events.
+* Exit codes from manual runs.
+* `/app/data/blog` and `/app/data/posted.json` on the mounted host directory.
+
+# Related
+
+* [Daily Run Guide](/guides/daily-run.md)
+* [Job 1089 Runtime Changes](/architecture/runtime-changes.md)
+* [Environment Variable Setup](/operations/environment-setup.md)
+* [Cron Lifecycle](/operations/cron-lifecycle.md)