feat(studio): daily Today-Hero proposal pipeline (v0.31.0)

Cross-store research (Apple, Play, Steam, Docker, VS Code,
Chrome Web Store, Flathub) consistently rewards editorial
curation over algorithmic recommendations — but manual
copywriting per release does not survive a solo-dev cadence.
This commit lands a daily-build pipeline so the Today-Hero
card stays fresh without operator hand-edits per release.

Pipeline shape (full design in docs/today-pipeline.md):

1. tools/today/collect.sh aggregates "what happened in the
   last 24 hours" across the F∆I monorepos: git log per repo,
   store-index seed.yaml diffs, architecture/system-gaps doc
   changes, Studio release tags, and (opt-in) audit-log
   highlights. Outputs plain text.

2. tools/today/propose.sh feeds the signal summary plus
   prompt.template.md to the operator's already-configured
   System-AI (Ollama default; OpenAI-compatible endpoints
   work via env-var override). Drafts N candidate stories as
   YAML files under ~/.fai/today/proposals/<date>/.

3. tools/today/accept.sh validates a chosen candidate against
   the today/v1 schema and the no-marketing-speak banned-word
   list, then atomic-renames it into ~/.fai/today/active.yaml.

4. Studio reads active.yaml at store-page init via the new
   TodayStoryLoader (lib/data/today_story_loader.dart). On any
   failure (file missing, schema mismatch, banned-words hit,
   parse error) it falls back to the compiled-in
   _kFallbackTodayStory so KRITIS deployments and fresh
   installs always render something sensible.

Trust + audit:
- All proposed and accepted stories live as plain YAML on disk.
- The pipeline calls only the operator's already-configured
  System-AI; it never reaches a CMS, never phones home, works
  air-gapped if the System-AI does.
- The bash accept gate AND the Dart loader both enforce the
  banned-word list — a hand-edited active.yaml that bypassed
  the shell still won't reach the UI.
- Removing the cron entry disables the pipeline; Studio falls
  back to the const story and continues to work.

Cron / launchd / systemd recipes documented in
tools/today/README.md.

Signed-off-by: flemming-it <stefan.a.flemming@googlemail.com>

tools/today/README.md

@@ -0,0 +1,73 @@
+# Today-Hero proposal tooling
+
+Daily-build pipeline for the editorial Today-Hero card in Studio's store.
+See `../../docs/today-pipeline.md` for the full design rationale.
+
+## Quick start
+
+```bash
+# 1. Generate today's proposals (calls the local Ollama by default).
+./propose.sh
+
+# 2. Skim them — they sit under ~/.fai/today/proposals/<ISO-DATE>/
+ls ~/.fai/today/proposals/
+
+# 3. Accept one. The chosen file becomes ~/.fai/today/active.yaml,
+#    which Studio reads at startup.
+./accept.sh ~/.fai/today/proposals/2026-05-08/candidate-2.yaml
+
+# 4. Restart Studio (or let the next launch pick it up).
+```
+
+## Schedule it
+
+### macOS — launchd
+
+```bash
+# Drop a plist that runs propose.sh every morning at 07:30 local time.
+# `launchctl load ~/Library/LaunchAgents/ai.flemming.fai.today.plist` to
+# install. The plist must point at the absolute path of propose.sh.
+```
+
+A starter plist lives at `launchd/ai.flemming.fai.today.plist`.
+
+### Linux — systemd timer
+
+```bash
+# Copy systemd/fai-today.{service,timer} into ~/.config/systemd/user/,
+# then `systemctl --user enable --now fai-today.timer`.
+```
+
+### Anywhere — cron
+
+```cron
+30 7 * * * /Users/flemming/.../tools/today/propose.sh > /tmp/fai-today.log 2>&1
+```
+
+## Provider override
+
+`propose.sh` defaults to Ollama at `http://127.0.0.1:11434` with the model
+`gemma3:4b`. Override via env vars:
+
+| Variable          | Default                          | Example                                         |
+|-------------------|----------------------------------|-------------------------------------------------|
+| `FAI_TODAY_API`   | `http://127.0.0.1:11434/api/generate` | `https://api.openai.com/v1/chat/completions` |
+| `FAI_TODAY_MODEL` | `gemma3:4b`                      | `gpt-4o-mini`                                   |
+| `FAI_TODAY_KEY`   | (unset)                          | `$OPENAI_API_KEY`                               |
+| `FAI_TODAY_N`     | `3`                              | `1` (single shot)                               |
+
+OpenAI-compatible endpoints will work as long as they speak `chat/completions`
+or `generate`; the script auto-detects from the URL path.
+
+## Trust model
+
+- Reads only `git log`, `git diff`, and the bundled `seed.yaml` of
+  installed F∆I monorepos. Never your audit log without explicit op-in.
+- Calls only the System-AI you've already configured for Studio. The same
+  privacy mode you set there applies here.
+- Writes only into `~/.fai/today/`. Nothing in `~/.fai/data/` or
+  `~/.fai/config.yaml` is touched.
+- Studio loads `active.yaml` at startup; if the file is missing or fails
+  schema validation, the compiled-in fallback story renders. KRITIS
+  fresh installs see the fallback until and unless an operator accepts a
+  proposal.

tools/today/accept.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# tools/today/accept.sh <proposal-path>
+#
+# Validates the chosen candidate, then atomically swaps it in as
+# ~/.fai/today/active.yaml. Studio reads that file at startup.
+set -euo pipefail
+
+if [ "${1:-}" = "" ]; then
+  printf 'Usage: %s <path-to-candidate.yaml>\n' "$0" >&2
+  exit 1
+fi
+
+src="$1"
+[ -f "$src" ] || { printf 'No such file: %s\n' "$src" >&2; exit 1; }
+
+# Schema gate. Block accept if the candidate is missing required
+# top-level keys or carries the wrong schema version. Studio
+# would silently fall back, but we want a loud failure here so
+# the operator knows the proposal was malformed.
+require_key() {
+  local key="$1"
+  if ! grep -qE "^$key:" "$src"; then
+    printf 'Reject: candidate is missing key `%s`.\n' "$key" >&2
+    exit 2
+  fi
+}
+
+if ! grep -qE '^schema:[[:space:]]*today/v1[[:space:]]*$' "$src"; then
+  printf 'Reject: candidate must declare `schema: today/v1`.\n' >&2
+  exit 2
+fi
+
+for k in badge_en badge_de title_en title_de body_en body_de icon cta; do
+  require_key "$k"
+done
+
+# Banned-words check (matches both DE and EN bodies/titles).
+banned='viral|killer|powerful|just[[:space:]]+works|revolutionary|game-changing|seamless|next-generation|cutting-edge|world-class|unprecedented'
+if grep -qiE "$banned" "$src"; then
+  printf 'Reject: candidate contains banned marketing language.\n' >&2
+  printf 'Hits:\n' >&2
+  grep -niE "$banned" "$src" >&2 || true
+  exit 3
+fi
+
+# Atomic move via copy-then-rename so Studio never reads a torn
+# half-written file even if it polls during the swap.
+dst="$HOME/.fai/today/active.yaml"
+mkdir -p "$(dirname "$dst")"
+tmp="$(mktemp "${dst}.XXXXXX")"
+cp "$src" "$tmp"
+mv "$tmp" "$dst"
+
+printf 'Accepted: %s\n  → %s\n' "$src" "$dst"
+printf 'Restart Studio (or wait for the next launch) to see it.\n'

tools/today/collect.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# tools/today/collect.sh
+#
+# Aggregates "what happened in the last N hours" across the F∆I
+# monorepos into a single plain-text summary the proposer feeds
+# to the System-AI.
+#
+# Touches only git history and the bundled store-index seed file.
+# Does not read the audit log without --with-audit.
+set -euo pipefail
+
+SINCE="${FAI_TODAY_SINCE:-24 hours ago}"
+
+# Walk every fai-* directory next to fai_studio so the collector
+# works from any of the sibling checkouts. Adjust here if the
+# layout ever changes.
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+emit_section() {
+  printf '\n## %s\n\n' "$1"
+}
+
+emit_section "RECENT COMMITS (last: $SINCE)"
+for repo in "$ROOT"/fai_*/; do
+  [ -d "$repo/.git" ] || continue
+  name="$(basename "$repo")"
+  log=$(git -C "$repo" log --since="$SINCE" --pretty='%h %s' 2>/dev/null || true)
+  if [ -n "$log" ]; then
+    printf '### %s\n%s\n\n' "$name" "$log"
+  fi
+done
+
+emit_section "STORE INDEX SEED CHANGES"
+seed="$ROOT/fai_platform/crates/fai_hub/store-index/seed.yaml"
+if [ -f "$seed" ] && [ -d "$ROOT/fai_platform/.git" ]; then
+  diff=$(git -C "$ROOT/fai_platform" log --since="$SINCE" --oneline -- \
+    crates/fai_hub/store-index/seed.yaml 2>/dev/null || true)
+  if [ -n "$diff" ]; then
+    printf '%s\n' "$diff"
+  else
+    printf '(no changes in window)\n'
+  fi
+fi
+
+emit_section "ARCHITECTURE / SYSTEM-GAPS CHANGES"
+arch_dir="$ROOT/fai_platform/docs"
+if [ -d "$arch_dir" ] && [ -d "$ROOT/fai_platform/.git" ]; then
+  changes=$(git -C "$ROOT/fai_platform" log --since="$SINCE" --oneline -- \
+    docs/architecture docs/advanced 2>/dev/null || true)
+  if [ -n "$changes" ]; then
+    printf '%s\n' "$changes"
+  else
+    printf '(no changes in window)\n'
+  fi
+fi
+
+emit_section "STUDIO RECENT RELEASES"
+studio="$ROOT/fai_studio"
+if [ -d "$studio/.git" ]; then
+  tags=$(git -C "$studio" log --since="$SINCE" --pretty='%h %s' \
+    --grep='^feat(studio)\|^chore(studio): bump' 2>/dev/null || true)
+  if [ -n "$tags" ]; then
+    printf '%s\n' "$tags"
+  else
+    printf '(no Studio release activity)\n'
+  fi
+fi
+
+emit_section "AUDIT-LOG HIGHLIGHTS"
+if [ "${FAI_TODAY_WITH_AUDIT:-0}" = "1" ] && command -v fai >/dev/null 2>&1; then
+  fai audit recent --limit 20 2>/dev/null | head -40 || \
+    printf '(audit query failed; daemon may be stopped)\n'
+else
+  printf '(audit pull disabled — set FAI_TODAY_WITH_AUDIT=1 to opt in)\n'
+fi

tools/today/prompt.template.md

@@ -0,0 +1,78 @@
+You are the Today-tab editor for the F∆I Platform Studio store.
+Your job is to draft ONE editorial story per run that the platform's
+solo developer (Stefan Flemming) will review and either accept or
+discard.
+
+## Project identity (do not deviate)
+
+F∆I Platform is a deterministic workflow engine for AI-assisted
+document processing in regulated environments. It runs WASM modules
+inside YAML flows, with sandbox-secure capability discovery.
+
+The product mantra is "Hub. Module. Flow." — the platform is the
+product, not specific modules. Operators run Studio (Flutter Desktop
+GUI) against a local hub binary.
+
+## What you write
+
+A bilingual story for the Today-Hero card on the store page. The
+operator opens the store, sees one hero card with:
+
+- A short uppercase BADGE (3-4 words, e.g. "CAPABILITY FEDERATION")
+- A headline TITLE (one sentence, max 12 words)
+- A BODY of 2-3 short sentences telling a single story arc
+- A CTA action that calls the operator forward
+
+EN and DE are written in parallel by you, in the same pass. Match
+register and length between languages — German operators must not
+feel like they're reading a translation.
+
+## Bans (hard)
+
+- Banned words: "viral", "killer", "powerful", "just works",
+  "revolutionary", "game-changing", "seamless", "next-generation",
+  "cutting-edge", "world-class", "unprecedented".
+- No private organisation names: never "ITDZ", "Kammergericht",
+  "HTW", "J∆I", or any specific institution. Generic terms only —
+  "a regulated organisation", "a public administration".
+- No emoji.
+- No "Co-authored-by Claude" or other AI attribution.
+
+## Output format (strict)
+
+Reply with ONE YAML document, no surrounding prose, no markdown
+fences. Schema:
+
+```yaml
+schema: today/v1
+badge_en: <STRING, ALL CAPS, ≤4 words>
+badge_de: <STRING, ALL CAPS, ≤4 words>
+title_en: <ONE SENTENCE, ≤12 words>
+title_de: <ONE SENTENCE, ≤12 words>
+body_en: |
+  <2-3 sentences. ≤80 words total. Single story arc.>
+body_de: |
+  <2-3 sentences. ≤80 words total. Single story arc.>
+icon: <one of: hub_outlined | account_tree_outlined | shield_outlined |
+       extension | bolt | menu_book_outlined | security |
+       auto_awesome | rocket_launch | timeline_outlined>
+cta: <one of: openSettings | none>
+cta_label_en: <≤5 words. Required when cta != none.>
+cta_label_de: <≤5 words. Required when cta != none.>
+```
+
+## Signal input
+
+Below is the "what happened in F∆I in the last 24 hours" summary —
+git log entries, store-index changes, audit-log highlights. Pick the
+ONE most operator-relevant thread and tell its story. If nothing
+notable happened, surface a longer-arc theme (recent week's progress,
+a soon-to-ship capability, a stability message).
+
+---
+
+{{SIGNAL_INPUT}}
+
+---
+
+Now write the YAML. One story. No explanation.

tools/today/propose.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# tools/today/propose.sh
+#
+# Orchestrates: collect → System-AI → write candidate YAML files.
+# Defaults to a local Ollama at 127.0.0.1:11434 with gemma3:4b.
+# See README.md for env-var overrides.
+#
+# Output:  ~/.fai/today/proposals/<ISO-DATE>/candidate-<n>.yaml
+# Operator then runs accept.sh with the chosen file.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+DATE="$(date -u +%Y-%m-%d)"
+OUT_DIR="${FAI_TODAY_OUT:-$HOME/.fai/today/proposals/$DATE}"
+N="${FAI_TODAY_N:-3}"
+API="${FAI_TODAY_API:-http://127.0.0.1:11434/api/generate}"
+MODEL="${FAI_TODAY_MODEL:-gemma3:4b}"
+KEY="${FAI_TODAY_KEY:-}"
+
+mkdir -p "$OUT_DIR"
+
+signals="$("$HERE/collect.sh")"
+template="$(cat "$HERE/prompt.template.md")"
+prompt="${template//\{\{SIGNAL_INPUT\}\}/$signals}"
+
+call_ollama() {
+  # Streaming off, single completion. The /api/generate endpoint
+  # returns one big JSON; we extract `.response`.
+  jq -n --arg model "$MODEL" --arg prompt "$prompt" \
+    '{model: $model, prompt: $prompt, stream: false}' \
+    | curl -fsS -X POST -H 'Content-Type: application/json' \
+        --data-binary @- "$API" \
+    | jq -r '.response'
+}
+
+call_openai_compatible() {
+  local body
+  body=$(jq -n --arg model "$MODEL" --arg prompt "$prompt" '{
+    model: $model,
+    messages: [{role: "user", content: $prompt}],
+    temperature: 0.6
+  }')
+  local hdr_args=()
+  if [ -n "$KEY" ]; then
+    hdr_args=(-H "Authorization: Bearer $KEY")
+  fi
+  printf '%s' "$body" \
+    | curl -fsS -X POST -H 'Content-Type: application/json' \
+        "${hdr_args[@]}" --data-binary @- "$API" \
+    | jq -r '.choices[0].message.content'
+}
+
+draft_one() {
+  case "$API" in
+    *"/generate"*)             call_ollama ;;
+    *"/chat/completions"*)     call_openai_compatible ;;
+    *)
+      printf 'unknown API path in %s — aborting\n' "$API" >&2
+      exit 2 ;;
+  esac
+}
+
+# Strip ```yaml fences if the model adds them despite the prompt.
+clean_yaml() {
+  sed -e '/^```yaml$/d' -e '/^```$/d' -e 's/^```$//'
+}
+
+for n in $(seq 1 "$N"); do
+  out="$OUT_DIR/candidate-$n.yaml"
+  printf 'Drafting candidate %d/%d via %s (%s)…\n' "$n" "$N" "$API" "$MODEL"
+  draft_one | clean_yaml > "$out"
+  printf '  → %s (%d bytes)\n' "$out" "$(wc -c < "$out")"
+done
+
+printf '\nDone. Skim with:\n  ls -la %s\n  for f in %s/*.yaml; do echo "=== $f ==="; cat "$f"; done\n' \
+  "$OUT_DIR" "$OUT_DIR"
+printf '\nAccept with:\n  %s/accept.sh <path-to-chosen.yaml>\n' "$HERE"