diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index f64e69b42..7bd52f2fd 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -97,7 +97,8 @@ jobs:
             tests/test_engine_unavailable_notice.bats \
             tests/test_batch_skip_reporting.bats \
             tests/test_review_one_pr_ci_pending.bats \
-            tests/test_release_registry.bats
+            tests/test_release_registry.bats \
+            tests/test_readme_refresh_helpers.bats
 
   template-drift:
     # Drift guard (#969): fail when a file committed in petry-projects/repo-template
diff --git a/.github/workflows/readme-refresh.yml b/.github/workflows/readme-refresh.yml
new file mode 100644
index 000000000..7a9a48855
--- /dev/null
+++ b/.github/workflows/readme-refresh.yml
@@ -0,0 +1,69 @@
+name: README Refresh
+
+# Weekly agent that refreshes the org "meta-repo" READMEs from live org state and
+# opens (or updates) one rolling PR per repo for human review. Documented repo-specific
+# workflow — no corresponding org template in standards/workflows/ (see AGENTS.md).
+
+on:
+  schedule:
+    # Weekly — Monday at 09:00 UTC
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Generate and diff only; do not create/update branches or PRs"
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: readme-refresh
+  cancel-in-progress: false
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+      ORG: ${{ vars.ORG || 'petry-projects' }}
+      DRY_RUN: ${{ inputs.dry_run || 'false' }}
+      # Pin via vars.CLAUDE_CODE_VERSION for reproducible caching; mirrors docs-health-check.yml.
+      CLAUDE_CODE_VERSION: ${{ vars.CLAUDE_CODE_VERSION || '2.1.138' }}
+
+    steps:
+      - name: Checkout agent repo
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Set up Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
+        with:
+          node-version: '20'
+
+      - name: Cache claude-code CLI
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
+        with:
+          path: ~/.npm-global
+          key: claude-code-${{ env.CLAUDE_CODE_VERSION }}-${{ runner.os }}
+
+      - name: Install Claude Code CLI
+        run: |
+          mkdir -p "$HOME/.npm-global"
+          npm config set prefix "$HOME/.npm-global"
+          echo "$HOME/.npm-global/bin" >> "$GITHUB_PATH"
+          export PATH="$HOME/.npm-global/bin:$PATH"
+          if command -v claude >/dev/null 2>&1; then
+            echo "claude-code cache hit: $(claude --version)"
+          else
+            npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" # NOSONAR
+          fi
+
+      - name: Run README refresh
+        env:
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_GH_PAT }}
+        run: bash scripts/aw-readme-refresh.sh
diff --git a/AGENTS.md b/AGENTS.md
index beb2808ab..3578beda5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -57,6 +57,13 @@ This is the `.github-private` org infrastructure repo for `petry-projects`. It c
   ≤15-min backstop) and a `workflow_run: completed` fast path (#898) that scopes the sweep to the
   completing CI run's PR(s) for near-instant re-review. It must not be removed by template syncs. If the org
   template gains an equivalent re-trigger sweep, remove this exception and defer to the template instead.
+- **Exception:** `readme-refresh.yml` (weekly org README refresh) is a documented repo-specific workflow
+  with no corresponding org template in `standards/workflows/`. It regenerates the four org "meta-repo"
+  READMEs (public + member-only org profiles, and the `.github` / `.github-private` repo landing pages)
+  from live org state via `scripts/aw-readme-refresh.sh` + `prompts/aw/readme-refresh.md`, then opens or
+  updates one rolling PR (`chore/readme-refresh`, label `readme-refresh`) per repo for human review. It
+  never direct-pushes. It must not be removed by template syncs. If the org template gains an equivalent,
+  remove this exception and defer to the template instead.
 - **Exception:** The `bats` test list in `lint.yml` is extended with repo-specific test files (e.g.
   `tests/test_push_protection.bats`) beyond the org template baseline. When adding new test files to this
   repo, add them to this list. Template syncs must not reset it to the base template list. This includes
diff --git a/prompts/aw/readme-refresh.md b/prompts/aw/readme-refresh.md
new file mode 100644
index 000000000..627cdb690
--- /dev/null
+++ b/prompts/aw/readme-refresh.md
@@ -0,0 +1,59 @@
+<!-- VARIABLES: TARGET_LABEL, TARGET_TYPE, LINT_MAXLEN, FACTS_BUNDLE, CURRENT_CONTENT -->
+You are the README Refresh agent for the `petry-projects` GitHub organization. Your job is to
+produce an accurate, well-structured Markdown body for **${TARGET_LABEL}**.
+
+## Authoritative facts (live org state)
+
+${FACTS_BUNDLE}
+
+## Current content of the target file
+
+The current content is between the markers below. It is **empty** if the file does not yet exist.
+
+<<<CURRENT_CONTENT_START
+${CURRENT_CONTENT}
+CURRENT_CONTENT_END
+
+## Task
+
+Target type: `${TARGET_TYPE}`. Produce the complete, final Markdown body for this file.
+
+- `org-profile-public` — the org's **public** profile page (`.github/profile/README.md`). A curated
+  landing page: a short intro, a Projects table (Repository / Description / Language), a Standards &
+  Practices section, and a Contributing section. Public audience.
+- `org-profile-member` — the org's **member-only** profile page (`.github-private/profile/README.md`),
+  shown to signed-in org members. Similar shape to the public profile but may reference private
+  automation, internal agents, and operational docs. If the current content is empty, create it fresh,
+  reusing the tone of the public profile.
+- `github-repo-readme` — the landing README for the `.github` repo itself. Describe what the repo holds
+  (org-wide GitHub config, CI templates in `standards/workflows/`, engineering standards in `standards/`).
+  If empty, create it fresh.
+- `github-private-repo-readme` — the landing README for the `.github-private` repo. Describe the agents,
+  prompts, scripts, frameworks, and scheduled automation. Keep the existing structure where it is good.
+
+## Rules (follow exactly)
+
+1. **Preserve curated prose.** Keep existing descriptions, tone, and structure where they are accurate.
+   Improve clarity only where it helps. Do **not** blank or downgrade good existing text.
+2. **Only correct what the facts show is wrong or missing:** add repositories present in the facts but
+   missing from the table; fix stale primary-language values; fix inaccurate framework and agent lists.
+3. **Never invent** repositories, agents, or frameworks that are not in the facts bundle above.
+4. For repos whose GitHub description is empty (flagged in the facts), **keep any existing curated
+   description** in the current content — do not replace it with an empty value.
+5. **Hard-wrap every prose line to at most ${LINT_MAXLEN} characters** — insert real line breaks so no
+   line exceeds the limit (a soft break inside a paragraph renders identically). Tables and fenced code
+   blocks are exempt. This is a strict CI lint rule (markdownlint MD013); overly long lines fail CI.
+6. If the target repo is `.github` (types `org-profile-public`, `github-repo-readme`): the first line
+   of the body MUST be a single top-level `# ` heading, and use `[text](url)` links — **no bare URLs**.
+7. Do **not** explain your reasoning, and do **not** add any preamble or trailing commentary.
+8. Emit the complete file body **between two marker lines**, exactly like this:
+
+   ```
+   ===README-BEGIN===
+   <the full markdown body goes here>
+   ===README-END===
+   ```
+
+   Put nothing except the file body between the markers, and nothing after `===README-END===`.
+9. If the current content is already fully accurate and needs no change, output exactly `SKIP`
+   (with no markers, no other text).
diff --git a/scripts/aw-readme-refresh.sh b/scripts/aw-readme-refresh.sh
new file mode 100644
index 000000000..12e9e02a1
--- /dev/null
+++ b/scripts/aw-readme-refresh.sh
@@ -0,0 +1,367 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# scripts/aw-readme-refresh.sh
+# Weekly README Refresh agent. Reads live org state, regenerates the four org
+# "meta-repo" READMEs via Claude, and opens (or updates) one rolling PR per repo.
+#
+# Targets:
+#   petry-projects/.github          profile/README.md   (public org profile)
+#   petry-projects/.github          README.md           (repo landing page)
+#   petry-projects/.github-private  README.md           (repo landing page)
+#   petry-projects/.github-private  profile/README.md   (member-only org profile)
+#
+# Environment:
+#   ORG                     — org login (default: petry-projects)
+#   DRY_RUN                 — if true, generate + diff only; no branch/PR (default: false)
+#   GH_TOKEN                — GitHub PAT with repo write on both target repos
+#   CLAUDE_CODE_OAUTH_TOKEN — Claude auth (read by the claude CLI)
+#   CLAUDE_MODEL            — model id (default: claude-sonnet-4-6)
+#   ACTION_TIMEOUT_SEC      — per-target claude timeout (default: 300)
+#   README_REFRESH_OUTPUT_DIR — if set, copy each generated file here (debug/dry-run inspection)
+
+ORG="${ORG:-petry-projects}"
+DRY_RUN="${DRY_RUN:-false}"
+CLAUDE_MODEL="${CLAUDE_MODEL:-claude-sonnet-4-6}"
+ACTION_TIMEOUT_SEC="${ACTION_TIMEOUT_SEC:-300}"
+BRANCH="chore/readme-refresh"
+LABEL="readme-refresh"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+PROMPT_TEMPLATE="$REPO_ROOT/prompts/aw/readme-refresh.md"
+
+# shellcheck source=scripts/lib/git-identity.sh
+source "$SCRIPT_DIR/lib/git-identity.sh"
+
+log()    { echo "[readme-refresh] $*" >&2; }
+notice() { echo "::notice::readme-refresh: $*"; }
+warn()   { echo "::warning::readme-refresh: $*"; }
+
+WORK_DIR="$(mktemp -d)"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+if [ -z "${GH_TOKEN:-}" ]; then
+  echo "::error::GH_TOKEN must be set" >&2
+  exit 1
+fi
+if [ ! -f "$PROMPT_TEMPLATE" ]; then
+  echo "::error::Prompt template not found at $PROMPT_TEMPLATE" >&2
+  exit 1
+fi
+
+# ── Facts bundle ──────────────────────────────────────────────────────────────
+# Assemble authoritative live org state so Claude never invents names.
+
+EMPTY_DESC_REPOS=""   # populated by gather_facts; surfaced in the PR body
+
+gather_facts() {
+  local facts_file="$WORK_DIR/facts.md"
+  local repo_json standards_list
+
+  repo_json=$(gh repo list "$ORG" --limit 1000 \
+    --json name,description,primaryLanguage,isArchived,isPrivate \
+    --jq 'sort_by(.name)' 2>/dev/null || echo "[]")
+
+  EMPTY_DESC_REPOS=$(echo "$repo_json" \
+    | jq -r '[.[] | select((.description // "") == "") | .name] | join(", ")' 2>/dev/null || echo "")
+  # gather_facts runs in a $(...) subshell, so persist this for the parent via a sidecar file.
+  printf '%s' "$EMPTY_DESC_REPOS" > "$WORK_DIR/empty_desc.txt"
+
+  # Standards docs live in the sibling .github repo; fetch via API (not checked out here).
+  standards_list=$(gh api "repos/$ORG/.github/contents/standards" \
+    --jq '[.[] | select((.name // "") | endswith(".md")) | .name | sub("\\.md$";"")] | sort | .[]' \
+    2>/dev/null || echo "(unavailable)")
+
+  {
+    echo "### Live repositories in \`$ORG\` (source of truth for the projects table)"
+    echo ""
+    echo '```json'
+    echo "$repo_json"
+    echo '```'
+    echo ""
+    if [ -n "$EMPTY_DESC_REPOS" ]; then
+      echo "Repos with an EMPTY GitHub description (keep any existing curated text; do not blank): ${EMPTY_DESC_REPOS}"
+      echo ""
+    fi
+    echo "### Standards docs in \`$ORG/.github/standards/\`"
+    echo ""
+    if [ -n "$standards_list" ]; then
+      echo "$standards_list" | sed 's/^/- /'
+    fi
+    echo ""
+    echo "### Custom agents in \`.github-private/agents/\`"
+    echo ""
+    local f name desc
+    for f in "$REPO_ROOT"/agents/*.md; do
+      [ -e "$f" ] || continue
+      name="$(basename "$f" .md)"
+      desc="$(awk '/^description:/{sub(/^description:[[:space:]]*/,"");gsub(/^["'"'"']|["'"'"']$/,"");print;exit}' "$f")"
+      printf -- '- `%s`: %s\n' "$name" "$desc"
+    done
+    echo ""
+    echo "### Installed frameworks in \`.github-private/frameworks/\` (from each VENDOR.md)"
+    echo ""
+    local d src
+    for d in "$REPO_ROOT"/frameworks/*/; do
+      [ -d "$d" ] || continue
+      name="$(basename "$d")"
+      src="$(grep -iE '^(source|upstream|tag|version)' "$d/VENDOR.md" 2>/dev/null | head -2 | tr '\n' '; ' | sed 's/; *$//' || true)"
+      printf -- '- `%s` (%s)\n' "$name" "${src:-vendored}"
+    done
+  } > "$facts_file"
+
+  echo "$facts_file"
+}
+
+# ── Prompt rendering ──────────────────────────────────────────────────────────
+# Scalars via envsubst; multiline blocks (facts, current content) injected by awk
+# to avoid ARG_MAX limits (same technique as release-notes.sh).
+
+render_prompt() {
+  if [ $# -lt 5 ]; then return 1; fi
+  local facts_file="$1" current_file="$2" target_label="$3" target_type="$4" maxlen="$5"
+  TARGET_LABEL="$target_label" TARGET_TYPE="$target_type" LINT_MAXLEN="$maxlen" \
+    envsubst '${TARGET_LABEL} ${TARGET_TYPE} ${LINT_MAXLEN}' < "$PROMPT_TEMPLATE" \
+    | awk -v ff="$facts_file" -v cf="$current_file" '
+        /\$\{FACTS_BUNDLE\}/    { while ((getline l < ff) > 0) print l; close(ff); next }
+        /\$\{CURRENT_CONTENT\}/ { while ((getline l < cf) > 0) print l; close(cf); next }
+        { print }'
+}
+
+# ── Content generation ────────────────────────────────────────────────────────
+
+generate_content() {
+  local prompt_file="$1"
+  local err_file="$WORK_DIR/claude-stderr.$$"
+  timeout "$ACTION_TIMEOUT_SEC" claude --print \
+    --model "$CLAUDE_MODEL" \
+    --disallowed-tools "Bash,Read,Write,Edit,Grep,Glob,WebFetch,WebSearch,Task,TodoWrite,NotebookEdit" \
+    < "$prompt_file" 2>"$err_file" || { warn "claude invocation failed: $(tail -n5 "$err_file" 2>/dev/null)"; echo ""; }
+}
+
+# Extract the file body between the sentinel markers the prompt requires. This is robust
+# against reasoning preambles / trailing commentary the model may add around the body.
+extract_readme() {
+  printf '%s\n' "$1" | awk '
+    /^===README-END===[[:space:]]*$/   { f=0 }
+    f                                   { print }
+    /^===README-BEGIN===[[:space:]]*$/ { f=1 }'
+}
+
+# Remove leading and trailing blank lines (interior blanks preserved).
+trim_blank_edges() {
+  printf '%s\n' "$1" | sed '/./,$!d' | tac | sed '/./,$!d' | tac
+}
+
+# Comma-list of body line numbers whose length exceeds maxlen, excluding table rows and
+# fenced code blocks (both exempt from markdownlint MD013). Empty if all lines fit.
+overlong_lines() {
+  local content="$1" maxlen="$2"
+  printf '%s\n' "$content" | awk -v max="$maxlen" '
+    /^[[:space:]]*```/  { infence = !infence; next }
+    infence             { next }
+    /^[[:space:]]*\|/   { next }
+    length > max        { printf "%s%d", (c++ ? "," : ""), NR }'
+}
+
+# Reject obviously-malformed output before writing (protects lint + prevents junk PRs).
+valid_content() {
+  local content="$1" target_type="$2"
+  [ -n "$content" ] || return 1
+  [ "$content" = "SKIP" ] && return 1
+  case "$target_type" in
+    org-profile-public|github-repo-readme)
+      # .github repo requires MD041: first line is a top-level heading.
+      printf '%s\n' "$content" | head -n1 | grep -q '^# ' || return 1
+      ;;
+  esac
+  return 0
+}
+
+# ── Per-repo processing ───────────────────────────────────────────────────────
+# Target matrix, grouped by repo. Fields: <rel_path>|<target_type>|<label>|<maxlen>
+
+targets_for_repo() {
+  if [ $# -lt 1 ]; then return 1; fi
+  case "$1" in
+    ".github")
+      printf '%s\n' \
+        "profile/README.md|org-profile-public|the PUBLIC org profile (.github/profile/README.md)|200" \
+        "README.md|github-repo-readme|the .github repo landing README|200"
+      ;;
+    ".github-private")
+      printf '%s\n' \
+        "README.md|github-private-repo-readme|the .github-private repo landing README|400" \
+        "profile/README.md|org-profile-member|the MEMBER-ONLY org profile (.github-private/profile/README.md)|400"
+      ;;
+  esac
+}
+
+process_repo() {
+  if [ $# -lt 2 ]; then return 1; fi
+  local repo="$1" facts_file="$2"
+  local full_repo="$ORG/$repo"
+  local dir="$WORK_DIR/$repo"
+  local LINT_WARNINGS=""
+
+  log "Cloning $full_repo"
+  git clone --quiet \
+    -c http.extraHeader="Authorization: Bearer ${GH_TOKEN}" \
+    "https://github.com/${full_repo}.git" "$dir"
+  local default_branch
+  default_branch="$(git -C "$dir" symbolic-ref --short HEAD)"
+  # Rolling branch: always reset to default HEAD so the PR reflects "main + fresh READMEs".
+  git -C "$dir" checkout -q -B "$BRANCH"
+
+  local changed=0 rel_path target_type label maxlen
+  while IFS='|' read -r rel_path target_type label maxlen; do
+    [ -n "$rel_path" ] || continue
+    local target_path="$dir/$rel_path"
+    local current_file="$WORK_DIR/current.$$"
+    if [ -f "$target_path" ]; then cp "$target_path" "$current_file"; else : > "$current_file"; fi
+
+    local prompt_file="$WORK_DIR/prompt.md"
+    render_prompt "$facts_file" "$current_file" "$label" "$target_type" "$maxlen" > "$prompt_file"
+
+    log "Generating: $repo/$rel_path ($target_type)"
+    local raw content violations="" attempt=1
+    while :; do
+      raw="$(generate_content "$prompt_file")"
+      if [ "$attempt" -eq 1 ] && [ "$(printf '%s' "$raw" | tr -d '[:space:]')" = "SKIP" ]; then
+        if [ -s "$current_file" ]; then
+          content="__SKIP__"; break
+        else
+          log "  → SKIP rejected: target is new/empty, retrying"
+          attempt=$((attempt + 1))
+          continue
+        fi
+      fi
+      content="$(trim_blank_edges "$(extract_readme "$raw")")"
+      if ! valid_content "$content" "$target_type"; then content="__INVALID__"; break; fi
+      violations="$(overlong_lines "$content" "$maxlen")"
+      if [ -z "$violations" ] || [ "$attempt" -ge 2 ]; then break; fi
+      log "  → retry: body line(s) over $maxlen chars at $violations"
+      {
+        printf '\n## Correction (attempt %d)\n' "$((attempt + 1))"
+        printf 'Your previous output had prose line(s) exceeding %s characters (body line(s): %s).\n' "$maxlen" "$violations"
+        printf 'Re-emit the FULL body between the markers with EVERY prose line hard-wrapped to <= %s characters. Tables and fenced code blocks are exempt.\n' "$maxlen"
+      } >> "$prompt_file"
+      attempt=$((attempt + 1))
+    done
+
+    if [ "$content" = "__SKIP__" ]; then
+      log "  → SKIP (already accurate)"
+      rm -f "$current_file"
+      continue
+    fi
+    if [ "$content" = "__INVALID__" ]; then
+      warn "  → invalid/empty output for $repo/$rel_path — leaving unchanged"
+      rm -f "$current_file"
+      continue
+    fi
+    if [ -n "$violations" ]; then
+      warn "  → $repo/$rel_path still has body line(s) over $maxlen ($violations) after retry — writing; trim before merge"
+      LINT_WARNINGS="${LINT_WARNINGS}- \`$rel_path\`: body line(s) exceed ${maxlen} chars (${violations})"$'\n'
+    fi
+
+    mkdir -p "$(dirname "$target_path")"
+    printf '%s\n' "$content" > "$target_path"
+    if [ -n "${README_REFRESH_OUTPUT_DIR:-}" ]; then
+      mkdir -p "$README_REFRESH_OUTPUT_DIR/$repo/$(dirname "$rel_path")"
+      cp "$target_path" "$README_REFRESH_OUTPUT_DIR/$repo/$rel_path"
+    fi
+    if git -C "$dir" diff --quiet -- "$rel_path" 2>/dev/null && \
+       [ -n "$(git -C "$dir" ls-files -- "$rel_path")" ]; then
+      log "  → no change"
+    else
+      log "  → updated"
+      changed=1
+    fi
+    rm -f "$current_file"
+  done < <(targets_for_repo "$repo")
+
+  if [ "$changed" -eq 0 ]; then
+    notice "$full_repo: all READMEs already accurate — nothing to do"
+    return 0
+  fi
+
+  git -C "$dir" add -A
+  if git -C "$dir" diff --cached --quiet; then
+    notice "$full_repo: no net changes after staging — skipping"
+    return 0
+  fi
+
+  echo "### $full_repo" >> "$WORK_DIR/summary.md"
+  git -C "$dir" --no-pager diff --cached --stat >> "$WORK_DIR/summary.md" 2>/dev/null || true
+
+  if [ "$DRY_RUN" = "true" ]; then
+    log "DRY-RUN: would open/update PR on $full_repo (branch $BRANCH). Diff:"
+    git -C "$dir" --no-pager diff --cached --stat >&2 || true
+    return 0
+  fi
+
+  ( cd "$dir" && setup_git_identity )
+  git -C "$dir" commit -q -m "docs: refresh org READMEs from live state (automated) [skip ci]"
+  git -C "$dir" push --force-with-lease --quiet origin "$BRANCH"
+
+  # Ensure the label exists (idempotent), then create the PR if none is open.
+  gh label create "$LABEL" --repo "$full_repo" --color BFD4F2 \
+    --description "Automated README refresh" >/dev/null 2>&1 || true
+
+  local existing
+  existing="$(gh pr list --repo "$full_repo" --head "$BRANCH" --state open \
+    --json url --jq '.[0]?.url' 2>/dev/null || echo "")"
+
+  local empty_note=""
+  [ -n "$EMPTY_DESC_REPOS" ] && empty_note=$'\n\n**Action needed:** these repos have empty GitHub descriptions — set them on the repo page so future refreshes can enrich the table: '"$EMPTY_DESC_REPOS"
+  local lint_note=""
+  [ -n "$LINT_WARNINGS" ] && lint_note=$'\n\n**⚠️ Trim before merge — these lines exceed the markdownlint length limit:**\n'"$LINT_WARNINGS"
+
+  if [ -n "$existing" ]; then
+    notice "$full_repo: updated existing PR $existing"
+  else
+    local url
+    url="$(gh pr create --repo "$full_repo" --base "$default_branch" --head "$BRANCH" \
+      --label "$LABEL" \
+      --title "docs: refresh org READMEs (automated)" \
+      --body "$(cat <<EOF
+## Automated README refresh
+
+Regenerated the org meta-repo README(s) in \`$full_repo\` from live org state
+(repository list, standards docs, agent profiles, and installed frameworks).
+
+Generated by the weekly \`readme-refresh\` workflow in \`$ORG/.github-private\`.
+Review the diff — curated prose is preserved; only missing/stale facts are corrected.${empty_note}${lint_note}
+EOF
+)")"
+    notice "$full_repo: opened PR $url"
+  fi
+}
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+log "Starting README refresh (org=$ORG, dry_run=$DRY_RUN, model=$CLAUDE_MODEL)"
+if ! command -v claude >/dev/null 2>&1; then
+  echo "::error::claude CLI not found on PATH" >&2
+  exit 1
+fi
+
+facts_file="$(gather_facts)"
+EMPTY_DESC_REPOS="$(cat "$WORK_DIR/empty_desc.txt" 2>/dev/null || echo "")"
+log "Facts bundle assembled ($(wc -l < "$facts_file") lines); empty-desc repos: ${EMPTY_DESC_REPOS:-none}"
+
+for _repo in ".github" ".github-private"; do
+  if ! process_repo "$_repo" "$facts_file"; then
+    warn "$ORG/$_repo: processing failed — continuing with remaining repos"
+  fi
+done
+
+if [ -n "${GITHUB_STEP_SUMMARY:-}" ] && [ -f "$WORK_DIR/summary.md" ]; then
+  {
+    echo "## README Refresh"
+    [ "$DRY_RUN" = "true" ] && echo "> **DRY-RUN** — no branches or PRs were created" && echo ""
+    cat "$WORK_DIR/summary.md"
+  } >> "$GITHUB_STEP_SUMMARY"
+fi
+
+log "Done"
diff --git a/tests/test_readme_refresh_helpers.bats b/tests/test_readme_refresh_helpers.bats
new file mode 100644
index 000000000..9dc9eb1d2
--- /dev/null
+++ b/tests/test_readme_refresh_helpers.bats
@@ -0,0 +1,128 @@
+#!/usr/bin/env bats
+# Unit tests for pure helper functions in scripts/aw-readme-refresh.sh:
+#   extract_readme, overlong_lines, valid_content
+#
+# Run: bats tests/test_readme_refresh_helpers.bats
+
+SCRIPT="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/scripts/aw-readme-refresh.sh"
+
+setup() {
+  # Extract only the pure helper function definitions; skip the main body
+  # that requires live env vars (GH_TOKEN, PROMPT_TEMPLATE, etc.)
+  eval "$(awk '
+    /^extract_readme\(\)/  { f=1 }
+    /^trim_blank_edges\(\)/{ f=1 }
+    /^overlong_lines\(\)/  { f=1 }
+    /^valid_content\(\)/   { f=1 }
+    f                      { print }
+    f && /^\}$/            { f=0 }
+  ' "$SCRIPT")"
+}
+
+# ── extract_readme ────────────────────────────────────────────────────────────
+
+@test "extract_readme: captures body between markers" {
+  raw="$(printf '%s\n' 'preamble' '===README-BEGIN===' '# Hello' 'body line' '===README-END===' 'epilogue')"
+  result="$(extract_readme "$raw")"
+  [ "$result" = "$(printf '%s\n' '# Hello' 'body line')" ]
+}
+
+@test "extract_readme: returns empty when markers are absent" {
+  result="$(extract_readme "no markers here")"
+  [ -z "$result" ]
+}
+
+@test "extract_readme: ignores reasoning preamble and trailing commentary" {
+  raw="$(printf '%s\n' 'Some reasoning...' '===README-BEGIN===' 'content' '===README-END===' 'extra')"
+  result="$(extract_readme "$raw")"
+  [ "$result" = "content" ]
+}
+
+@test "extract_readme: markers with trailing whitespace are recognised" {
+  raw="$(printf '%s\n' '===README-BEGIN===   ' 'line' '===README-END===  ')"
+  result="$(extract_readme "$raw")"
+  [ "$result" = "line" ]
+}
+
+# ── overlong_lines ────────────────────────────────────────────────────────────
+
+@test "overlong_lines: returns empty when all lines fit within maxlen" {
+  result="$(overlong_lines "short line" 120)"
+  [ -z "$result" ]
+}
+
+@test "overlong_lines: reports the line number of an overlong prose line" {
+  long="$(printf '%201s' '' | tr ' ' 'x')"
+  content="$(printf '%s\n' 'ok' "$long")"
+  result="$(overlong_lines "$content" 200)"
+  [ "$result" = "2" ]
+}
+
+@test "overlong_lines: reports multiple overlong line numbers as comma list" {
+  long="$(printf '%201s' '' | tr ' ' 'x')"
+  content="$(printf '%s\n' "$long" 'ok' "$long")"
+  result="$(overlong_lines "$content" 200)"
+  [ "$result" = "1,3" ]
+}
+
+@test "overlong_lines: skips table rows (lines starting with |)" {
+  long_table="| $(printf '%300s' '' | tr ' ' 'x') |"
+  result="$(overlong_lines "$long_table" 200)"
+  [ -z "$result" ]
+}
+
+@test "overlong_lines: skips content inside fenced code blocks" {
+  long="$(printf '%300s' '' | tr ' ' 'x')"
+  content="$(printf '%s\n' '```' "$long" '```')"
+  result="$(overlong_lines "$content" 200)"
+  [ -z "$result" ]
+}
+
+@test "overlong_lines: counts prose lines outside code fence after fence closes" {
+  long="$(printf '%201s' '' | tr ' ' 'x')"
+  content="$(printf '%s\n' '```' "$long" '```' "$long")"
+  result="$(overlong_lines "$content" 200)"
+  [ "$result" = "4" ]
+}
+
+# ── valid_content ─────────────────────────────────────────────────────────────
+
+@test "valid_content: rejects empty content" {
+  run valid_content "" "github-private-repo-readme"
+  [ "$status" -ne 0 ]
+}
+
+@test "valid_content: rejects the literal string SKIP" {
+  run valid_content "SKIP" "github-private-repo-readme"
+  [ "$status" -ne 0 ]
+}
+
+@test "valid_content: accepts non-empty content for private-readme type (no H1 required)" {
+  run valid_content "Some body content" "github-private-repo-readme"
+  [ "$status" -eq 0 ]
+}
+
+@test "valid_content: rejects org-profile-public with no top-level heading" {
+  run valid_content "$(printf '%s\n' '## H2 opener' 'body')" "org-profile-public"
+  [ "$status" -ne 0 ]
+}
+
+@test "valid_content: accepts org-profile-public with correct H1 first line" {
+  run valid_content "$(printf '%s\n' '# Org Name' 'body')" "org-profile-public"
+  [ "$status" -eq 0 ]
+}
+
+@test "valid_content: rejects github-repo-readme missing top-level heading" {
+  run valid_content "$(printf '%s\n' 'no heading here' 'body')" "github-repo-readme"
+  [ "$status" -ne 0 ]
+}
+
+@test "valid_content: accepts github-repo-readme with H1 first line" {
+  run valid_content "$(printf '%s\n' '# Repo Title' 'body')" "github-repo-readme"
+  [ "$status" -eq 0 ]
+}
+
+@test "valid_content: accepts org-profile-member with any non-empty content" {
+  run valid_content "$(printf '%s\n' 'member section' 'more')" "org-profile-member"
+  [ "$status" -eq 0 ]
+}