diff --git a/README.md b/README.md
index 4bd45f3..2a49f51 100644
--- a/README.md
+++ b/README.md
@@ -310,6 +310,28 @@ Expect the architecture to continue being refined toward:
 
 ---
 
+## Upstream fork — knoe-db
+
+This repository is an independent fork of the upstream knoe-db project:
+
+```
+git@git.knoe.dev:knoe-dev/knoe-db.git
+```
+
+Upstream changes are pulled into a dated review branch (`upstream/knoe-db/YYYYMMDD`) using the sync script, inspected, and selectively merged into `main`.
+
+```bash
+# Preview what the script will do
+./scripts/sync_upstream_knoe_db.sh --dry-run
+
+# Run the sync (requires a clean working tree)
+./scripts/sync_upstream_knoe_db.sh
+```
+
+See [`docs/upstream-knoe-db-sync.md`](docs/upstream-knoe-db-sync.md) for the full review-and-merge procedure.
+
+---
+
 ## License
 
 Add the project license here.
diff --git a/docs/upstream-knoe-db-sync.md b/docs/upstream-knoe-db-sync.md
new file mode 100644
index 0000000..391ce57
--- /dev/null
+++ b/docs/upstream-knoe-db-sync.md
@@ -0,0 +1,122 @@
+# Upstream knoe-db Sync Procedure
+
+This repo is an independent fork of the upstream knoe-db project hosted at:
+
+```
+git@git.knoe.dev:knoe-dev/knoe-db.git
+```
+
+The script `scripts/sync_upstream_knoe_db.sh` automates fetching upstream changes
+and staging them in a dedicated review branch so they can be inspected and selectively
+merged into `main`.
+
+---
+
+## Quick start
+
+```bash
+chmod +x scripts/sync_upstream_knoe_db.sh
+./scripts/sync_upstream_knoe_db.sh
+```
+
+Use `--dry-run` to preview what the script would do without touching the repo:
+
+```bash
+./scripts/sync_upstream_knoe_db.sh --dry-run
+```
+
+> **Requires a clean working tree.** The script will exit with an error if
+> `git diff` or `git diff --cached` reports any changes. Stash or commit
+> your work first:
+>
+> ```bash
+> git stash          # or: git add -A && git commit -m "wip: stash before upstream sync"
+> ./scripts/sync_upstream_knoe_db.sh
+> git stash pop      # restore your work afterwards
+> ```
+>
+> If you only want to inspect what the script would do without touching the
+> repo at all, `--dry-run` bypasses the clean-tree check.
+
+---
+
+## What the script does
+
+1. **Registers the upstream remote** `upstream-knoe-db` (idempotent — safe to re-run).
+2. **Fetches** `upstream-knoe-db/main` (no local branches are modified).
+3. **Creates a timestamped review branch** `upstream/knoe-db/YYYYMMDD` pointing at the
+   tip of the upstream fetch.
+4. **Returns you to your previous branch** automatically.
+5. **Prints next steps** with ready-to-paste git commands.
+
+---
+
+## Review and merge workflow
+
+### 1. See what changed
+
+```bash
+# Commits in upstream not yet in main
+git log main..upstream/knoe-db/$(date +%Y%m%d) --oneline
+
+# Full diff scoped to the knoe-db/ directory
+git diff main...upstream/knoe-db/$(date +%Y%m%d) -- knoe-db/
+```
+
+### 2. Check out the review branch
+
+```bash
+git checkout upstream/knoe-db/$(date +%Y%m%d)
+```
+
+Browse, test, or cherry-pick individual commits as needed.
+
+### 3. Merge into main
+
+When the changes look good:
+
+```bash
+git checkout main
+git merge --no-ff upstream/knoe-db/$(date +%Y%m%d) \
+  -m "chore(knoe-db): merge upstream $(date +%Y%m%d)"
+```
+
+Resolve any conflicts, then:
+
+```bash
+git push origin main
+```
+
+### 4. Open a PR / MR (recommended)
+
+Push the review branch and open a pull request so the team can review before
+merging into `main`:
+
+```bash
+git push origin upstream/knoe-db/$(date +%Y%m%d)
+# then open a PR targeting main
+```
+
+---
+
+## Keeping the upstream remote up to date
+
+The script is idempotent — running it again on a later date will fetch the latest
+upstream state and create a new dated branch (e.g. `upstream/knoe-db/20260601`).
+Old review branches can be deleted once merged:
+
+```bash
+git branch -d upstream/knoe-db/20260523
+git push origin --delete upstream/knoe-db/20260523
+```
+
+---
+
+## Adjusting the upstream branch name
+
+If the upstream project uses a branch other than `main` (e.g. `master` or `develop`),
+edit the `UPSTREAM_BRANCH` variable near the top of `scripts/sync_upstream_knoe_db.sh`:
+
+```bash
+UPSTREAM_BRANCH="master"   # ← change as needed
+```
diff --git a/scripts/sync_upstream_knoe_db.sh b/scripts/sync_upstream_knoe_db.sh
new file mode 100755
index 0000000..e1dc538
--- /dev/null
+++ b/scripts/sync_upstream_knoe_db.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# sync_upstream_knoe_db.sh — Pull upstream knoe-db changes into a review branch.
+#
+# Usage:
+#   ./scripts/sync_upstream_knoe_db.sh [--dry-run]
+#
+# What it does:
+#   1. Ensures the 'upstream-knoe-db' remote points to git@git.knoe.dev:knoe-dev/knoe-db.git
+#   2. Fetches the upstream default branch
+#   3. Creates a timestamped branch  upstream/knoe-db/YYYYMMDD  from the fetch
+#   4. Prints next steps for review and merge
+#
+# Run from the knoe-db/ subdirectory or the repo root (script auto-detects).
+
+set -euo pipefail
+
+UPSTREAM_REMOTE="upstream-knoe-db"
+UPSTREAM_URL="git@git.knoe.dev:knoe-dev/knoe-db.git"
+UPSTREAM_BRANCH="main"          # adjust if upstream uses a different default branch
+DATE_TAG="$(date +%Y%m%d)"
+REVIEW_BRANCH="upstream/knoe-db/${DATE_TAG}"
+DRY_RUN=false
+
+# ── argument parsing ──────────────────────────────────────────────────────────
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+    *) echo "Unknown argument: $arg" >&2; exit 1 ;;
+  esac
+done
+
+run() {
+  if $DRY_RUN; then
+    echo "[dry-run] $*"
+  else
+    "$@"
+  fi
+}
+
+# ── locate the knoe-db git worktree ───────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+KNOE_DB_DIR="${REPO_ROOT}/knoe-db"
+
+if [ ! -d "${KNOE_DB_DIR}/.git" ] && [ ! -f "${KNOE_DB_DIR}/.git" ]; then
+  # knoe-db may be a plain directory inside a mono-repo; operate from repo root
+  GIT_DIR="${REPO_ROOT}"
+else
+  GIT_DIR="${KNOE_DB_DIR}"
+fi
+
+echo "==> Working in git repo: ${GIT_DIR}"
+cd "${GIT_DIR}"
+
+# ── ensure we are on a clean working tree ────────────────────────────────────
+if ! $DRY_RUN; then
+  if ! git diff --quiet || ! git diff --cached --quiet; then
+    echo "ERROR: Working tree has uncommitted changes. Stash or commit before syncing." >&2
+    exit 1
+  fi
+fi
+
+# ── add / verify upstream remote ─────────────────────────────────────────────
+if git remote get-url "${UPSTREAM_REMOTE}" &>/dev/null; then
+  CURRENT_URL="$(git remote get-url "${UPSTREAM_REMOTE}")"
+  if [ "${CURRENT_URL}" != "${UPSTREAM_URL}" ]; then
+    echo "==> Updating remote '${UPSTREAM_REMOTE}' URL to ${UPSTREAM_URL}"
+    run git remote set-url "${UPSTREAM_REMOTE}" "${UPSTREAM_URL}"
+  else
+    echo "==> Remote '${UPSTREAM_REMOTE}' already set to ${UPSTREAM_URL}"
+  fi
+else
+  echo "==> Adding remote '${UPSTREAM_REMOTE}' → ${UPSTREAM_URL}"
+  run git remote add "${UPSTREAM_REMOTE}" "${UPSTREAM_URL}"
+fi
+
+# ── fetch upstream ────────────────────────────────────────────────────────────
+echo "==> Fetching ${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH} …"
+run git fetch "${UPSTREAM_REMOTE}" "${UPSTREAM_BRANCH}"
+
+# ── create review branch ──────────────────────────────────────────────────────
+if git show-ref --verify --quiet "refs/heads/${REVIEW_BRANCH}"; then
+  echo "==> Branch '${REVIEW_BRANCH}' already exists — skipping creation."
+  echo "    Delete it first if you want a fresh sync:  git branch -D ${REVIEW_BRANCH}"
+else
+  echo "==> Creating review branch '${REVIEW_BRANCH}' from ${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH}"
+  run git checkout -b "${REVIEW_BRANCH}" "${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH}"
+  run git checkout -        # return to previous branch
+fi
+
+# ── summary ───────────────────────────────────────────────────────────────────
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Upstream sync complete."
+echo ""
+echo "  Review branch : ${REVIEW_BRANCH}"
+echo "  Upstream      : ${UPSTREAM_URL} (${UPSTREAM_BRANCH})"
+echo ""
+echo "  Next steps:"
+echo "    1. Inspect the incoming changes:"
+echo "       git log main..${REVIEW_BRANCH} --oneline"
+echo "       git diff main...${REVIEW_BRANCH} -- knoe-db/"
+echo ""
+echo "    2. Check out the review branch and resolve any conflicts:"
+echo "       git checkout ${REVIEW_BRANCH}"
+echo ""
+echo "    3. Merge (or cherry-pick) into main when satisfied:"
+echo "       git checkout main"
+echo "       git merge --no-ff ${REVIEW_BRANCH} -m 'chore(knoe-db): merge upstream ${DATE_TAG}'"
+echo ""
+echo "    4. Push and open a PR / MR for team review."
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"