From 37087e792530e5ba344d1314cdfb3e60723b4971 Mon Sep 17 00:00:00 2001
From: stephan <s.wilkens@gmx.net>
Date: Sun, 28 Dec 2025 23:51:01 +0100
Subject: [PATCH] docs: define update status reporting

---
 CHANGELOG.md                                  |  1 +
 README.md                                     |  1 +
 docs/update-client.md                         |  4 +++
 docs/update-status.md                         | 25 +++++++++++++++++++
 env.example                                   |  1 +
 .../requirements/tasks/TASK_000029.md         |  3 ++-
 6 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 docs/update-status.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5da2326..c343ab0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,7 @@ By: Codex (GPT-5)
 | 28.12.2025 | ⚙️ Code | ID: Update-Config Keys in Settings/ENV/README definiert. By: Codex (GPT-5) |
 | 28.12.2025 | 📝 Req | ID: Update-Flow fuer Client dokumentiert. By: Codex (GPT-5) |
 | 28.12.2025 | 📝 Req | ID: Update-Flow Prototyp dokumentiert. By: Codex (GPT-5) |
+| 28.12.2025 | 📝 Req | ID: Update-Status-Schema dokumentiert. By: Codex (GPT-5) |
 | 28.12.2025 | ⚙️ Code | ID: Update-Client Prototyp-Skript hinzugefuegt. By: Codex (GPT-5) |
 
 ---
diff --git a/README.md b/README.md
index 4a5dbd0..7380a34 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,7 @@ Set in `/etc/skd/env` (see `env.example`):
   - `SKD_UPDATE_URL` (default `https://update.wlkns.org`)
   - `SKD_UPDATE_TOKEN` (API token for update service)
   - `SKD_UPDATE_INTERVAL` (seconds; default 3600)
+  - `SKD_UPDATE_STATUS_URL` (default `https://update.wlkns.org/status`)
 Notes:
 - `./scripts/install.sh` will create `/etc/skd/env` from `env.example` if missing (edit afterwards) and ensure the `skd` service user/group exist.
 
diff --git a/docs/update-client.md b/docs/update-client.md
index f19a3da..35fb815 100644
--- a/docs/update-client.md
+++ b/docs/update-client.md
@@ -42,3 +42,7 @@ Beispiel:
 ## Constraints
 - Update-Service ist extern (update.wlkns.org).
 - Service muss als root stoppen/starten koennen.
+
+## Status Reporting
+- Status wird per HTTP POST an `https://update.wlkns.org/status` gemeldet.
+- Schema siehe `docs/update-status.md`.
diff --git a/docs/update-status.md b/docs/update-status.md
new file mode 100644
index 0000000..a83af27
--- /dev/null
+++ b/docs/update-status.md
@@ -0,0 +1,25 @@
+ID: DOC_000005 | Version: 0.1.0 | Status: Draft
+By: Codex (GPT-5)
+
+# Update Status Reporting
+
+## Purpose
+Definiert das Status-Schema fuer Update-Resultate und den Uebertragungsweg.
+
+## Status Schema (JSON)
+```json
+{
+  "device_id": "<hostname>",
+  "version": "0.1.2",
+  "status": "success|failed",
+  "error": "<optional message>",
+  "timestamp": "2025-12-28T12:34:56Z"
+}
+```
+
+## Transport
+- HTTP POST an `https://update.wlkns.org/status`
+- Auth: Bearer Token (`SKD_UPDATE_TOKEN`)
+
+## Notes
+- Statusmeldungen sind best-effort; Fehler beim Senden blockieren kein Update.
diff --git a/env.example b/env.example
index 9c7368b..a2f1822 100644
--- a/env.example
+++ b/env.example
@@ -25,5 +25,6 @@ SKD_NOTIFY_TIMEOUT=5
 SKD_UPDATE_URL=https://update.wlkns.org
 SKD_UPDATE_TOKEN=
 SKD_UPDATE_INTERVAL=3600
+SKD_UPDATE_STATUS_URL=https://update.wlkns.org/status
 # Set to true to test without performing real system changes
 SKD_DRY_RUN=false
diff --git a/project-management/requirements/tasks/TASK_000029.md b/project-management/requirements/tasks/TASK_000029.md
index 37ae192..39fdd76 100644
--- a/project-management/requirements/tasks/TASK_000029.md
+++ b/project-management/requirements/tasks/TASK_000029.md
@@ -1,4 +1,4 @@
-ID: TASK_000029 | Version: 0.1.0 | Status: Draft
+ID: TASK_000029 | Version: 0.1.0 | Status: In Progress
 By: Codex (GPT-5)
 
 # TASK_000029: Report update status
@@ -13,6 +13,7 @@ US_000028
 - Status-Schema definieren (Version, Ergebnis, Fehler, Zeitpunkt).
 - Transportweg festlegen (z.B. HTTP POST oder Log-Export).
 - Erfolg/Fehler konsistent dokumentieren.
+- Schema dokumentiert in `docs/update-status.md`.
 
 ## Definition of Done (DoD)
 - Status-Schema dokumentiert.