docs(deploy): add Flux/Talos deploy guide + sibling-repos PAT helper script

scripts/setup-sibling-repos-token.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Create a Gitea PAT with read access to the sibling API repos and store it as
+# the SIBLING_REPOS_TOKEN action secret on leeworks-agents/api-company.
+#
+# Why this script exists:
+#   - Gitea's build-docs workflow checks out sibling repos. The auto-injected
+#     GITEA_TOKEN is scoped to THIS repo only and cannot read them, and
+#     GITEA_TOKEN is a reserved secret name that cannot be overridden.
+#   - `tea` cannot CREATE a PAT (no such command), and Gitea's token-creation
+#     API requires BASIC AUTH (your password) — a token cannot mint a token.
+#   - `tea` CAN set the action secret using its existing login.
+#
+# So: this prompts for your password ONCE, mints the PAT via the API, and pipes
+# it straight into `tea` as the secret. The PAT value is never written to disk.
+#
+# Usage:  bash scripts/setup-sibling-repos-token.sh
+set -euo pipefail
+
+GITEA_URL="https://gitea.leeworks.dev"
+GITEA_USER="0xWheatyz"
+REPO="leeworks-agents/api-company"
+SECRET_NAME="SIBLING_REPOS_TOKEN"
+TOKEN_NAME="sibling-repos-readonly-$(date +%Y%m%d)"
+
+command -v curl >/dev/null || { echo "curl required"; exit 1; }
+command -v tea  >/dev/null || { echo "tea required";  exit 1; }
+command -v python3 >/dev/null || { echo "python3 required"; exit 1; }
+
+echo "Gitea user: $GITEA_USER  ($GITEA_URL)"
+read -r -s -p "Gitea password (for $GITEA_USER): " GITEA_PASS
+echo
+
+# Create a read-only PAT. scope read:repository lets the build-docs workflow
+# clone the sibling repos. Adjust scopes here if your Gitea version differs.
+resp="$(curl -fsS -X POST \
+  -u "${GITEA_USER}:${GITEA_PASS}" \
+  -H 'Content-Type: application/json' \
+  -d "{\"name\":\"${TOKEN_NAME}\",\"scopes\":[\"read:repository\"]}" \
+  "${GITEA_URL}/api/v1/users/${GITEA_USER}/tokens")" || {
+    echo "Token creation failed. Check password / 2FA (2FA blocks basic-auth token creation)." >&2
+    exit 1
+  }
+unset GITEA_PASS
+
+PAT="$(printf '%s' "$resp" | python3 -c 'import sys,json; print(json.load(sys.stdin)["sha1"])')"
+[ -n "$PAT" ] || { echo "Could not parse token from response: $resp" >&2; exit 1; }
+echo "PAT '${TOKEN_NAME}' created."
+
+# Store it as the action secret via tea (overwrites if it already exists).
+printf '%s' "$PAT" | tea actions secrets create "$SECRET_NAME" --repo "$REPO" --stdin
+unset PAT
+
+echo "Secret '${SECRET_NAME}' set on ${REPO}."
+echo "Verify:  tea actions secrets list --repo ${REPO}"
+echo "Then re-run build-docs:  tea actions runs ...  (or push to main / workflow_dispatch)"