jekyll-theme-zer0 1.18.1 → 1.19.0

data/scripts/lib/hub.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+# =============================================================================
+# scripts/lib/hub.rb — shared helpers for the org content hub tooling
+# =============================================================================
+#
+# Used by:
+#   scripts/sync-hub-metadata.rb    dashboard data refresh (_data/hub_index.yml)
+#   scripts/provision-org-sites.rb  Pages scaffold rollout to org repos
+#
+# The registry (_data/hub.yml) is the single source of truth; see its header
+# for the architecture. Everything here is read-only with respect to this
+# repository — callers decide what to write.
+# =============================================================================
+
+require 'yaml'
+require 'json'
+require 'date'
+require 'base64'
+require 'open3'
+
+module Hub
+  ROOT        = File.expand_path('../..', __dir__)
+  CONFIG_FILE = File.join(ROOT, '_data', 'hub.yml')
+
+  GENERATED_HEADER = <<~HEADER
+    # =============================================================================
+    # GENERATED FILE — do not edit by hand.
+    # Regenerate with: ./scripts/sync-hub-metadata.sh
+    # Source registry: _data/hub.yml
+    # =============================================================================
+  HEADER
+
+  module_function
+
+  def log_info(msg)
+    puts "[INFO]  #{msg}"
+  end
+
+  def log_warn(msg)
+    warn "[WARN]  #{msg}"
+  end
+
+  def log_error(msg)
+    warn "[ERROR] #{msg}"
+  end
+
+  # Permit Date/Time; fall back for the older macOS system Ruby (2.6) whose
+  # safe loader signature differs.
+  def load_yaml(path)
+    YAML.load_file(path, permitted_classes: [Date, Time])
+  rescue ArgumentError
+    YAML.load_file(path)
+  end
+
+  def run_cmd(*cmd)
+    out, err, status = Open3.capture3(*cmd)
+    raise "command failed: #{cmd.join(' ')}\n#{err}" unless status.success?
+
+    out
+  end
+
+  # gh api wrapper returning parsed JSON, or nil on a 404.
+  def gh_api(path)
+    out, err, status = Open3.capture3('gh', 'api', path)
+    return JSON.parse(out) if status.success?
+    return nil if err.include?('404') || out.include?('"status": "404"')
+
+    raise "gh api #{path} failed:\n#{err}"
+  end
+
+  def load_registry
+    raise "registry not found: #{CONFIG_FILE}" unless File.exist?(CONFIG_FILE)
+
+    load_yaml(CONFIG_FILE)
+  end
+
+  def validate_registry(cfg)
+    return ['registry is not a YAML mapping'] unless cfg.is_a?(Hash)
+
+    errors = []
+    errors << 'org: must be a non-empty string' unless cfg['org'].is_a?(String) && !cfg['org'].strip.empty?
+
+    if cfg.key?('auto_discover') && ![true, false].include?(cfg['auto_discover'])
+      errors << 'auto_discover: must be true or false'
+    end
+
+    if cfg.key?('exclude_repos') && !(cfg['exclude_repos'].is_a?(Array) && cfg['exclude_repos'].all? { |r| r.is_a?(String) })
+      errors << 'exclude_repos: must be a list of strings'
+    end
+
+    pages = cfg['pages'] || {}
+    errors << 'pages: must be a mapping' unless pages.is_a?(Hash)
+    if pages.is_a?(Hash) && !(pages['theme_repo'].is_a?(String) && pages['theme_repo'].include?('/'))
+      errors << 'pages.theme_repo: must be an <owner>/<repo> string'
+    end
+
+    defaults = cfg['defaults'] || {}
+    errors << 'defaults: must be a mapping' unless defaults.is_a?(Hash)
+    if defaults.is_a?(Hash) && defaults.key?('exclude') &&
+       !(defaults['exclude'].is_a?(Array) && defaults['exclude'].all? { |p| p.is_a?(String) })
+      errors << 'defaults.exclude: must be a list of glob strings'
+    end
+
+    repos = cfg['repos'] || []
+    errors << 'repos: must be a list' unless repos.is_a?(Array)
+    if repos.is_a?(Array)
+      repos.each_with_index do |repo, i|
+        unless repo.is_a?(Hash) && repo['name'].is_a?(String) && !repo['name'].strip.empty?
+          errors << "repos[#{i}]: needs a non-empty `name`"
+          next
+        end
+        errors << "repos[#{i}] (#{repo['name']}): name contains unsafe characters" unless repo['name'].match?(%r{\A[\w.-]+\z})
+      end
+    end
+
+    if cfg['auto_discover'] == false && repos.empty?
+      errors << 'auto_discover is false but repos: is empty — nothing to include'
+    end
+
+    errors
+  end
+
+  # Org repos that are hub content sites, with per-repo registry overrides
+  # merged on top. Requires `gh` unless auto_discover is false.
+  def discover_repos(cfg)
+    org      = cfg['org']
+    excluded = cfg['exclude_repos'] || []
+    manual   = (cfg['repos'] || []).map { |r| [r['name'], r] }.to_h
+
+    discovered =
+      if cfg.fetch('auto_discover', true)
+        json = run_cmd('gh', 'repo', 'list', org, '--limit', '200',
+                       '--json', 'name,description,defaultBranchRef,isArchived,pushedAt')
+        JSON.parse(json).reject { |r| r['isArchived'] }.map do |r|
+          {
+            'name'        => r['name'],
+            'description' => r['description'].to_s,
+            'branch'      => r.dig('defaultBranchRef', 'name') || 'main',
+            'pushed_at'   => r['pushedAt'].to_s
+          }
+        end
+      else
+        manual.values.map { |r| { 'branch' => 'main' }.merge(r) }
+      end
+
+    discovered
+      .reject  { |r| excluded.include?(r['name']) }
+      .map     { |r| r.merge(manual[r['name']] || {}) { |_k, auto, over| (over.nil? || over == '') ? auto : over } }
+      .sort_by { |r| r['name'] }
+  end
+
+  def excluded?(rel, patterns)
+    patterns.any? do |pat|
+      rel == pat ||
+        File.fnmatch?(pat, rel, File::FNM_PATHNAME) ||
+        (pat.end_with?('/**') && rel.start_with?("#{pat[0..-4]}/"))
+    end
+  end
+
+  def slugify(segment)
+    segment.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-+|-+\z/, '')
+  end
+
+  def humanize(name)
+    name.tr('-_', '  ').split.map(&:capitalize).join(' ')
+  end
+
+  FRONT_MATTER_RE = /\A---\s*\n(.*?\n?)^---\s*\n/m
+
+  def split_front_matter(raw)
+    match = raw.match(FRONT_MATTER_RE)
+    return [nil, raw] unless match
+
+    fm = begin
+      YAML.safe_load(match[1], permitted_classes: [Date, Time]) || {}
+    rescue StandardError
+      nil
+    end
+    return [nil, raw] unless fm.is_a?(Hash)
+
+    [fm, match.post_match]
+  end
+
+  # Title of a markdown document: front matter `title`, else first H1, else
+  # the humanized fallback.
+  def title_of(raw, fallback)
+    fm, body = split_front_matter(raw)
+    (fm && fm['title']) || body[/^\#\s+(.+?)\s*$/, 1] || humanize(fallback)
+  end
+
+  # The markdown content files of a repo tree (array of path strings),
+  # filtered through the registry's exclude patterns.
+  def content_paths(paths, exclude_patterns)
+    paths.select { |p| p.end_with?('.md') }
+         .reject { |p| p.split('/').any? { |seg| seg.start_with?('.') } }
+         .reject { |p| excluded?(p, exclude_patterns) }
+         .sort
+  end
+
+  # Pretty-permalink URL of a repo-root or nested page on the published site.
+  #   site_url must end with '/'. README/index map to their directory root.
+  def page_url(site_url, rel)
+    segments = rel.sub(/\.md\z/i, '').split('/')
+    segments.pop if %w[index readme].include?(segments.last.downcase)
+    segments.empty? ? site_url : "#{site_url}#{segments.join('/')}/"
+  end
+end

data/scripts/provision-org-sites.rb

@@ -0,0 +1,252 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# provision-org-sites.rb
+# =============================================================================
+#
+# Rolls the GitHub Pages scaffold out to the org repos registered in
+# `_data/hub.yml`, so each publishes its own project site at
+# https://<org>.github.io/<repo>/ rendered with the zer0-mistakes theme
+# (`remote_theme`) — content never leaves the source repo.
+#
+# Per repo it:
+#   1. clones the repo and analyzes its content layout (sections, timeline),
+#   2. renders templates/org-site/* (_config.yml + _data/navigation/main.yml),
+#   3. opens a pull request with the scaffold (branch: zer0/pages-scaffold) —
+#      or pushes directly with --direct,
+#   4. with --enable-pages, enables GitHub Pages ("deploy from branch").
+#
+# Safety:
+#   - A repo whose _config.yml was NOT generated by this script is skipped
+#     (never clobbers a hand-rolled site config).
+#   - Re-running is idempotent: identical scaffold -> no new PR/commit.
+#
+# Usage:
+#   ruby scripts/provision-org-sites.rb --dry-run            # preview everything
+#   ruby scripts/provision-org-sites.rb                      # open scaffold PRs
+#   ruby scripts/provision-org-sites.rb --enable-pages       # PRs + enable Pages
+#   ruby scripts/provision-org-sites.rb --repos 2005 --direct
+#   ruby scripts/provision-org-sites.rb --stage /tmp/out     # render files locally only
+#   ruby scripts/provision-org-sites.rb --check              # validate registry + templates
+#
+# Requires `gh` (repo + pages write for the real run) and `git`.
+# =============================================================================
+
+require 'optparse'
+require 'fileutils'
+require 'tmpdir'
+require_relative 'lib/hub'
+
+TEMPLATE_DIR    = File.join(Hub::ROOT, 'templates', 'org-site')
+CONFIG_TEMPLATE = File.join(TEMPLATE_DIR, '_config.yml.template')
+NAV_TEMPLATE    = File.join(TEMPLATE_DIR, 'navigation-main.yml.template')
+SCAFFOLD_MARKER = 'zer0-mistakes org hub scaffold'
+BRANCH_NAME     = 'zer0/pages-scaffold'
+
+def render(template, vars)
+  vars.reduce(File.read(template, encoding: 'utf-8')) do |text, (key, value)|
+    text.gsub("{{#{key}}}", value.to_s)
+  end
+end
+
+def yaml_quote(text)
+  text.to_s.gsub('"', '\"')
+end
+
+# Nav entries for the repo's root content files and sections, rendered as
+# site-relative URLs (the theme's relative_url filter prefixes the baseurl).
+def nav_items(clone, files)
+  items = +''
+  files.reject { |f| f.include?('/') }
+       .reject { |f| %w[index readme].include?(File.basename(f, '.md').downcase) }
+       .each do |f|
+    base = File.basename(f, '.md')
+    items << "- title: #{Hub.title_of(File.read(File.join(clone, f), encoding: 'utf-8'), base)}\n" \
+             "  icon: bi-clock-history\n" \
+             "  url: /#{base}/\n"
+  end
+  files.select { |f| f.include?('/') }.map { |f| f.split('/').first }.uniq.sort.each do |dir|
+    index = File.join(clone, dir, 'index.md')
+    title = File.exist?(index) ? Hub.title_of(File.read(index, encoding: 'utf-8'), dir) : Hub.humanize(dir)
+    items << "- title: #{title}\n" \
+             "  icon: bi-folder\n" \
+             "  url: /#{dir}/\n"
+  end
+  items.chomp
+end
+
+def scaffold_files(repo, cfg, clone)
+  excludes = (cfg['defaults'] || {})['exclude'] || []
+  files    = Hub.content_paths(Dir.chdir(clone) { Dir.glob('**/*.md') }, excludes)
+
+  vars = {
+    'ORG'              => cfg['org'],
+    'REPO'             => repo['name'],
+    'REPO_TITLE'       => yaml_quote(repo['title'] || repo['name']),
+    'REPO_DESCRIPTION' => yaml_quote(repo['description']),
+    'THEME_REPO'       => cfg.dig('pages', 'theme_repo'),
+    'BRANCH'           => repo['branch'],
+    'NAV_ITEMS'        => nav_items(clone, files)
+  }
+
+  {
+    '_config.yml'               => render(CONFIG_TEMPLATE, vars),
+    '_data/navigation/main.yml' => render(NAV_TEMPLATE, vars)
+  }
+end
+
+def write_scaffold(base_dir, rendered)
+  changed = []
+  rendered.each do |rel, content|
+    path = File.join(base_dir, rel)
+    next if File.exist?(path) && File.read(path, encoding: 'utf-8') == content
+
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, content)
+    changed << rel
+  end
+  changed
+end
+
+def open_pr(repo, cfg, clone, changed, direct:)
+  org  = cfg['org']
+  slug = "#{org}/#{repo['name']}"
+
+  Dir.chdir(clone) do
+    if direct
+      Hub.run_cmd('git', 'add', *changed)
+      Hub.run_cmd('git', 'commit', '-m', 'feat(pages): publish via GitHub Pages with the zer0-mistakes theme')
+      Hub.run_cmd('git', 'push', 'origin', repo['branch'])
+      Hub.log_info "  pushed scaffold directly to #{slug}@#{repo['branch']}"
+      return
+    end
+
+    Hub.run_cmd('git', 'checkout', '-B', BRANCH_NAME)
+    Hub.run_cmd('git', 'add', *changed)
+    Hub.run_cmd('git', 'commit', '-m', 'feat(pages): publish via GitHub Pages with the zer0-mistakes theme')
+    Hub.run_cmd('git', 'push', '--force', 'origin', BRANCH_NAME)
+
+    existing = JSON.parse(Hub.run_cmd('gh', 'pr', 'list', '--repo', slug, '--head', BRANCH_NAME,
+                                      '--state', 'open', '--json', 'url'))
+    if existing.empty?
+      body = <<~BODY
+        Adds the GitHub Pages scaffold generated by
+        [zer0-mistakes/scripts/provision-org-sites.rb](https://github.com/#{cfg.dig('pages', 'theme_repo')}/blob/main/scripts/provision-org-sites.rb):
+
+        - `_config.yml` — publishes this repo at https://#{org}.github.io/#{repo['name']}/ using `remote_theme: #{cfg.dig('pages', 'theme_repo')}`. Content stays plain markdown; the GitHub Pages default plugins render it.
+        - `_data/navigation/main.yml` — navbar/sidebar entries for the repo's sections.
+
+        Once merged (with Pages enabled, "deploy from branch"), the site builds automatically on every push.
+
+        🤖 Generated with [Claude Code](https://claude.com/claude-code)
+      BODY
+      url = Hub.run_cmd('gh', 'pr', 'create', '--repo', slug, '--base', repo['branch'], '--head', BRANCH_NAME,
+                        '--title', 'feat(pages): publish via GitHub Pages with the zer0-mistakes theme',
+                        '--body', body).strip
+      Hub.log_info "  opened PR: #{url}"
+    else
+      Hub.log_info "  updated existing PR: #{existing.first['url']}"
+    end
+  end
+end
+
+def enable_pages(repo, cfg)
+  org = cfg['org']
+  out, err, status = Open3.capture3(
+    'gh', 'api', '-X', 'POST', "repos/#{org}/#{repo['name']}/pages",
+    '-f', "source[branch]=#{repo['branch']}", '-f', 'source[path]=/'
+  )
+  if status.success?
+    Hub.log_info "  Pages enabled: #{JSON.parse(out)['html_url']}"
+  elsif err.include?('409') || out.include?('already exists')
+    Hub.log_info '  Pages already enabled'
+  else
+    Hub.log_warn "  could not enable Pages: #{err.lines.first&.strip}"
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+options = { mode: :provision, dry_run: false, repos: nil, direct: false, enable_pages: false, stage: nil }
+OptionParser.new do |opts|
+  opts.banner = 'Usage: ruby scripts/provision-org-sites.rb [options]'
+  opts.on('--check',         'validate registry and templates, no network')   { options[:mode] = :check }
+  opts.on('--dry-run',       'show planned changes without pushing anything') { options[:dry_run] = true }
+  opts.on('--repos LIST',    'comma-separated subset of repos')               { |v| options[:repos] = v.split(',').map(&:strip) }
+  opts.on('--direct',        'commit to the default branch instead of a PR')  { options[:direct] = true }
+  opts.on('--enable-pages',  'enable GitHub Pages (deploy from branch)')      { options[:enable_pages] = true }
+  opts.on('--stage DIR',     'render scaffold files into DIR/<repo>/ only')   { |v| options[:stage] = v }
+end.parse!
+
+cfg    = Hub.load_registry
+errors = Hub.validate_registry(cfg)
+[CONFIG_TEMPLATE, NAV_TEMPLATE].each do |t|
+  errors << "missing template: #{t.sub("#{Hub::ROOT}/", '')}" unless File.exist?(t)
+end
+
+unless errors.empty?
+  errors.each { |e| Hub.log_error(e) }
+  exit 1
+end
+
+if options[:mode] == :check
+  Hub.log_info 'hub registry and org-site templates are valid'
+  exit 0
+end
+
+repos = Hub.discover_repos(cfg)
+repos.select! { |r| options[:repos].include?(r['name']) } if options[:repos]
+if repos.empty?
+  Hub.log_warn 'no repos to provision (check org, exclude_repos, or --repos filter)'
+  exit 0
+end
+
+Hub.log_info "Provisioning #{repos.size} repo(s) in #{cfg['org']}: #{repos.map { |r| r['name'] }.join(', ')}"
+
+Dir.mktmpdir('hub-provision') do |tmp|
+  repos.each do |repo|
+    slug  = "#{cfg['org']}/#{repo['name']}"
+    clone = File.join(tmp, repo['name'])
+    Hub.log_info "#{slug}:"
+    Hub.run_cmd('git', 'clone', '--quiet', '--branch', repo['branch'],
+                "https://github.com/#{slug}.git", clone)
+
+    existing_config = File.join(clone, '_config.yml')
+    if File.exist?(existing_config) && !File.read(existing_config, encoding: 'utf-8').include?(SCAFFOLD_MARKER)
+      Hub.log_warn '  has a hand-rolled _config.yml — skipping (manage it in the repo itself)'
+      next
+    end
+
+    rendered = scaffold_files(repo, cfg, clone)
+
+    if options[:stage]
+      stage_dir = File.join(options[:stage], repo['name'])
+      write_scaffold(stage_dir, rendered)
+      Hub.log_info "  staged scaffold in #{stage_dir}"
+      next
+    end
+
+    changed = options[:dry_run] ? rendered.keys.reject { |rel| File.exist?(File.join(clone, rel)) && File.read(File.join(clone, rel), encoding: 'utf-8') == rendered[rel] } : write_scaffold(clone, rendered)
+
+    if changed.empty?
+      Hub.log_info '  scaffold already up to date'
+    elsif options[:dry_run]
+      Hub.log_info "  DRY: would update #{changed.join(', ')} and open a PR"
+    else
+      open_pr(repo, cfg, clone, changed, direct: options[:direct])
+    end
+
+    if options[:enable_pages]
+      if options[:dry_run]
+        Hub.log_info '  DRY: would enable GitHub Pages (deploy from branch)'
+      else
+        enable_pages(repo, cfg)
+      end
+    end
+  end
+end
+
+Hub.log_info 'Provisioning complete'

data/scripts/provision-org-sites.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# =============================================================================
+# provision-org-sites.sh
+# =============================================================================
+#
+# Thin wrapper around scripts/provision-org-sites.rb.
+#
+# Rolls the GitHub Pages scaffold (templates/org-site/*) out to the org repos
+# registered in _data/hub.yml so each publishes at https://<org>.github.io/<repo>/
+# using this theme via remote_theme. Content never leaves the source repo.
+#
+# Usage:
+#   ./scripts/provision-org-sites.sh --dry-run         # preview everything
+#   ./scripts/provision-org-sites.sh                   # open scaffold PRs
+#   ./scripts/provision-org-sites.sh --enable-pages    # PRs + enable Pages
+#   ./scripts/provision-org-sites.sh --check           # validate registry + templates
+#
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec ruby "${SCRIPT_DIR}/provision-org-sites.rb" "$@"

data/scripts/sync-hub-metadata.rb

@@ -0,0 +1,184 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# sync-hub-metadata.rb
+# =============================================================================
+#
+# Refreshes the org content hub dashboard data. Content stays in the source
+# repos (each publishes its own GitHub Pages site at
+# https://<org>.github.io/<repo>/ — see scripts/provision-org-sites.rb); this
+# script only gathers METADATA about them via the GitHub API:
+#
+#   _data/hub_index.yml       — per-repo stats for the /hub/ dashboard
+#                               (page counts, sections, Pages status, links)
+#   _data/navigation/hub.yml  — sidebar tree for the hub pages (sidebar.nav: hub)
+#
+# Nothing is cloned and no content is copied into this repository. Output is
+# deterministic for unchanged sources, so the scheduled workflow only commits
+# real changes.
+#
+# Usage:
+#   ruby scripts/sync-hub-metadata.rb              # refresh dashboard data
+#   ruby scripts/sync-hub-metadata.rb --check      # validate registry/output only (CI gate)
+#   ruby scripts/sync-hub-metadata.rb --dry-run    # print planned writes, change nothing
+#
+# Requires the `gh` CLI (read scope). `--check` needs only the Ruby stdlib.
+# =============================================================================
+
+require 'optparse'
+require 'fileutils'
+require_relative 'lib/hub'
+
+INDEX_FILE = File.join(Hub::ROOT, '_data', 'hub_index.yml')
+NAV_FILE   = File.join(Hub::ROOT, '_data', 'navigation', 'hub.yml')
+
+def check_generated_output
+  errors = []
+  if File.exist?(INDEX_FILE)
+    index = Hub.load_yaml(INDEX_FILE)
+    if index.is_a?(Hash) && index['repos'].is_a?(Array)
+      index['repos'].each do |repo|
+        errors << "hub_index repo #{repo['name']}: missing site_url" unless repo['site_url'].to_s.start_with?('https://')
+      end
+    else
+      errors << '_data/hub_index.yml: missing repos list'
+    end
+  end
+  errors
+end
+
+# Gathers everything the dashboard needs about one repo from the GitHub API:
+# the markdown tree (for counts/sections), the Pages site status, and whether
+# the Pages scaffold (_config.yml) has landed.
+def inspect_repo(repo, cfg)
+  org      = cfg['org']
+  excludes = (cfg['defaults'] || {})['exclude'] || []
+
+  tree  = Hub.gh_api("repos/#{org}/#{repo['name']}/git/trees/#{repo['branch']}?recursive=1")
+  paths = (tree ? tree['tree'] : []).select { |e| e['type'] == 'blob' }.map { |e| e['path'] }
+  files = Hub.content_paths(paths, excludes)
+
+  pages    = Hub.gh_api("repos/#{org}/#{repo['name']}/pages")
+  site_url = (pages && pages['html_url']) || "https://#{org}.github.io/#{repo['name']}/"
+  site_url += '/' unless site_url.end_with?('/')
+
+  sections = files.select { |f| f.include?('/') }.group_by { |f| f.split('/').first }.sort.map do |dir, pages_in|
+    {
+      'name'  => dir,
+      'title' => section_title(org, repo, dir),
+      'url'   => "#{site_url}#{dir}/",
+      'count' => pages_in.count { |f| File.basename(f, '.md').downcase != 'index' }
+    }
+  end
+
+  root_pages = files.reject { |f| f.include?('/') }
+                    .reject { |f| %w[index readme].include?(File.basename(f, '.md').downcase) }
+                    .map { |f| { 'title' => Hub.humanize(File.basename(f, '.md')), 'url' => Hub.page_url(site_url, f) } }
+
+  {
+    'name'          => repo['name'],
+    'title'         => repo['title'] || repo['name'],
+    'description'   => repo['description'].to_s,
+    'url'           => "https://github.com/#{org}/#{repo['name']}",
+    'site_url'      => site_url,
+    'pages_enabled' => !pages.nil?,
+    'scaffolded'    => paths.include?('_config.yml'),
+    'branch'        => repo['branch'],
+    'pushed_at'     => repo['pushed_at'].to_s,
+    'page_count'    => files.size,
+    'sections'      => sections,
+    'root_pages'    => root_pages
+  }
+end
+
+# Title of a section's index page (one contents API call), falling back to a
+# humanized directory name.
+def section_title(org, repo, dir)
+  doc = Hub.gh_api("repos/#{org}/#{repo['name']}/contents/#{dir}/index.md?ref=#{repo['branch']}")
+  return Hub.humanize(dir) unless doc && doc['content']
+
+  Hub.title_of(Base64.decode64(doc['content']).force_encoding('utf-8'), dir)
+rescue StandardError
+  Hub.humanize(dir)
+end
+
+def build_index(cfg, repos)
+  {
+    'org'    => cfg['org'],
+    'totals' => { 'repos' => repos.size, 'pages' => repos.sum { |r| r['page_count'] } },
+    'repos'  => repos
+  }
+end
+
+def build_nav(repos)
+  items = [{ 'title' => 'Hub Dashboard', 'icon' => 'bi-grid-1x2', 'url' => '/hub/' }]
+  repos.each do |repo|
+    children = [{ 'title' => 'Site Home', 'url' => repo['site_url'] }]
+    repo['root_pages'].each { |p| children << { 'title' => p['title'], 'url' => p['url'] } }
+    repo['sections'].each   { |s| children << { 'title' => s['title'], 'url' => s['url'] } }
+    items << {
+      'title'    => repo['title'],
+      'icon'     => 'bi-journal-richtext',
+      'url'      => repo['site_url'],
+      'children' => children
+    }
+  end
+  items
+end
+
+def write_generated_yaml(path, data, dry_run:)
+  content = Hub::GENERATED_HEADER + data.to_yaml.sub(/\A---\n/, '')
+  if File.exist?(path) && File.read(path, encoding: 'utf-8') == content
+    Hub.log_info "unchanged: #{path.sub("#{Hub::ROOT}/", '')}"
+  elsif dry_run
+    Hub.log_info "DRY: would write #{path.sub("#{Hub::ROOT}/", '')}"
+  else
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, content)
+    Hub.log_info "wrote #{path.sub("#{Hub::ROOT}/", '')}"
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+options = { mode: :sync, dry_run: false }
+OptionParser.new do |opts|
+  opts.banner = 'Usage: ruby scripts/sync-hub-metadata.rb [--check|--dry-run]'
+  opts.on('--check',   'validate registry and generated data, no writes') { options[:mode] = :check }
+  opts.on('--dry-run', 'print planned actions without writing')           { options[:dry_run] = true }
+end.parse!
+
+cfg    = Hub.load_registry
+errors = Hub.validate_registry(cfg)
+errors += check_generated_output if options[:mode] == :check && errors.empty?
+
+unless errors.empty?
+  errors.each { |e| Hub.log_error(e) }
+  exit 1
+end
+
+if options[:mode] == :check
+  Hub.log_info 'hub registry and generated data are valid'
+  exit 0
+end
+
+repos = Hub.discover_repos(cfg)
+if repos.empty?
+  Hub.log_warn 'no repos found (check org and exclude_repos)'
+  exit 0
+end
+
+Hub.log_info "Inspecting #{repos.size} repo(s) in #{cfg['org']}: #{repos.map { |r| r['name'] }.join(', ')}"
+inspected = repos.map do |repo|
+  info = inspect_repo(repo, cfg)
+  state = info['pages_enabled'] ? "live at #{info['site_url']}" : 'Pages NOT enabled'
+  Hub.log_info "  #{info['name']}: #{info['page_count']} pages, #{info['sections'].size} sections — #{state}"
+  info
+end
+
+write_generated_yaml(INDEX_FILE, build_index(cfg, inspected), dry_run: options[:dry_run])
+write_generated_yaml(NAV_FILE, build_nav(inspected), dry_run: options[:dry_run])
+Hub.log_info 'Hub metadata refresh complete'