From feadda663ab0e4fa129fb8a7aea15c07e389c941 Mon Sep 17 00:00:00 2001
From: OpenVelo Agent <openvelo-agent@openvelo.org>
Date: Tue, 4 Aug 2026 18:00:52 +0000
Subject: [PATCH] docs: update documentation to OKF v0.1 format

---
 docs/architecture/config-schema.md   | 20 +++++++++++++-------
 docs/architecture/system-overview.md |  4 ++--
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/docs/architecture/config-schema.md b/docs/architecture/config-schema.md
index 4e9d6cf..512e73c 100644
--- a/docs/architecture/config-schema.md
+++ b/docs/architecture/config-schema.md
@@ -41,13 +41,15 @@ environment for the container to boot.
 `DEFAULTS` in `config.py` provides fallback strings that `apply_defaults`
 fills into the merged map **before** validation runs:
 
-| Default key           | Default value     |
-|-----------------------|-------------------|
-| `VISIBILITY`          | `public`          |
-| `THROWNBACK_PREFIX`   | `Throwback:`      |
-| `MAX_RETRIES`         | `3`               |
-| `TZ`                  | `Europe/Berlin`   |
-| `RUN_AT`              | `09:00`           |
+| Default key           | Default value                              |
+|-----------------------|-------------------------------------------|
+| `VISIBILITY`          | `public`                                   |
+| `THROWNBACK_PREFIX`   | `Throwback:`                               |
+| `MAX_RETRIES`         | `3`                                        |
+| `TZ`                  | `Europe/Berlin`                            |
+| `RUN_AT`              | `09:00`                                    |
+| `BLOG_REPO_URL`       | `https://git.chaospott.de/Chaospott/site`  |
+| `BLOG_DIR`            | `blog` (resolved relative to `data_dir`)   |
 
 Because every required key carries a default, a freshly-initialised
 container can still boot to validate the scaffold, but the operator
@@ -68,6 +70,8 @@ ideally `SITE_URL`) to make a real run.
 | `run_at`                | `str`     | `RUN_AT`                                     |
 | `tz`                    | `str`     | `TZ`                                         |
 | `data_dir`              | `Path`    | Constant: `Path("/app/data")`                |
+| `blog_repo_url`         | `str`     | `BLOG_REPO_URL`                              |
+| `blog_dir`              | `Path`    | `BLOG_DIR` resolved against `data_dir`       |
 
 # Validation Behaviour
 
@@ -80,6 +84,8 @@ problem joined with `"; "`. Validation covers:
 * `MASTODON_BASE_URL` and `SITE_URL` parse via `urllib.parse.urlparse`
   with an `http`/`https` scheme and a non-empty `netloc`.
 * `VISIBILITY` is one of `{"public", "unlisted"}` (`ALLOWED_VISIBILITY`).
+* `BLOG_REPO_URL` (optional, has default) parses via `urllib.parse.urlparse`
+  with an `http`/`https` scheme and a non-empty `netloc` when present.
 * `TZ` resolves via `zoneinfo.ZoneInfo`.
 * `MAX_RETRIES` parses as a non-negative integer (rejects bools).
 
diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md
index 8b2c651..10593bf 100644
--- a/docs/architecture/system-overview.md
+++ b/docs/architecture/system-overview.md
@@ -34,7 +34,7 @@ foreground of the `cron` process. Each scheduled invocation calls
 | `tenbackward.config`     | Loads `.env` + process env, applies defaults, validates schema, produces a typed `Config` dataclass.       |
 | `tenbackward.logging_setup` | JSON formatter (one log record per line), secret redaction, and `log_startup` / `log_error` / `log_run_summary` helpers. |
 | `tenbackward.state`      | Read/write of `posted.json` (atomic temp-file replace).                                                    |
-| `tenbackward.blog`       | Stubbed blog clone/update helper (lands in a follow-up job).                                              |
+| `tenbackward.blog`       | GitPython `ensure_repo()` — clones the configured blog repo on first run, fast-forwards it via `pull --ff-only` thereafter, with exponential-backoff retries on transient network errors. |
 | `/etc/cron.d/tenbackward`| Rendered cron file. One daily line that `cd /app` and runs `python -m tenbackward`.                        |
 
 # Communication & Wiring
@@ -80,7 +80,7 @@ foreground of the `cron` process. Each scheduled invocation calls
 | `/repo/src/tenbackward/config.py`   | Env merging, defaults, validation, `Config` dataclass, `ConfigError`.            |
 | `/repo/src/tenbackward/logging_setup.py` | JSON formatter, secret redaction, structured event helpers.                 |
 | `/repo/src/tenbackward/state.py`    | `posted.json` read/write with atomic temp-file replace.                         |
-| `/repo/src/tenbackward/blog.py`     | Stubbed blog clone helper (not yet wired into the pipeline).                    |
+| `/repo/src/tenbackward/blog.py`     | `ensure_repo()` — GitPython clone + fast-forward pull with `2^n` retry/backoff; raises `BlogRepoError` on local modifications or exhausted retries. |
 | `/repo/.env.example`                | Canonical list of environment variables.                                        |
 | `/repo/docker-compose.yml`          | Service definition; binds env vars from the host `.env`.                        |
 | `/repo/Dockerfile`                  | Builds the runtime image.                                                       |