jekyll-theme-zer0 1.28.0 → 1.30.0

data/scripts/ai/usage_report.rb

@@ -0,0 +1,225 @@
+#!/usr/bin/env ruby
+# =============================================================================
+# usage_report.rb — publish a job's AI usage records (summary, artifact, PR comment)
+# -----------------------------------------------------------------------------
+# The reporting half of AI metering. usage.rb captured one JSONL record per AI
+# call into AI_USAGE_DIR/records.jsonl; this script, run at the end of the
+# job (the claude-run composite calls it automatically), does four things:
+#
+#   1. ATTRIBUTE  — resolve which PR the spend belongs to: an explicit --pr,
+#                   the pull_request event payload, or the pr-result.txt file
+#                   the factory/fleet agents write after opening a PR (that
+#                   run's records become the PR's CREATION cost).
+#   2. CONSUME    — move records.jsonl to a reported-*.jsonl file (so a second
+#                   AI step in the same job never double-reports) and print
+#                   `file=` / `name=` to $GITHUB_OUTPUT for the artifact upload.
+#   3. SUMMARIZE  — append a per-call table to $GITHUB_STEP_SUMMARY.
+#   4. COMMENT    — upsert ONE sticky "AI usage & cost" comment on the PR,
+#                   found by its <!-- lh-ai-usage --> marker (never
+#                   `--edit-last`, which grabs whatever the bot said last).
+#                   The comment embeds its own base64 data blob, so each run
+#                   merges records by id — cumulative, idempotent, and safe to
+#                   re-run. Concurrent jobs can still race the read-merge-write
+#                   (last writer wins for the VIEW); the artifacts + nightly
+#                   ledger remain the source of truth.
+#
+# Every dollar figure is API-equivalent: what the tokens would bill at list
+# prices. Subscription (OAuth) runs cost $0 marginal — the label says so.
+# Best-effort by design: metering must never fail the job. Stdlib + `gh` only.
+#
+#   ruby scripts/ai/usage_report.rb [--pr N] [--pr-result pr-result.txt]
+# =============================================================================
+require 'json'
+require 'time'
+require 'digest'
+require 'securerandom'
+require_relative 'usage'
+
+MARKER    = '<!-- lh-ai-usage -->'.freeze
+DATA_HEAD = '<!-- lh-ai-usage-data:'.freeze
+MAX_BLOB_RECORDS = 150   # older records fold into a rollup so the comment stays < 64KB
+MAX_TABLE_ROWS   = 30
+
+pr_arg = nil
+pr_result_file = 'pr-result.txt'
+args = ARGV.dup
+until args.empty?
+  case (a = args.shift)
+  when '--pr'        then pr_arg = args.shift.to_i
+  when '--pr-result' then pr_result_file = args.shift.to_s
+  end
+end
+
+# --- 1. load this job's records ------------------------------------------------
+src = AIUsage.records_path
+records = File.exist?(src) ? File.read(src, encoding: 'UTF-8').split("\n").map { |l| JSON.parse(l) rescue nil }.compact : []
+if records.empty?
+  warn '[usage_report] no AI usage records this job — nothing to report.'
+  File.open(ENV['GITHUB_OUTPUT'], 'a') { |io| io.puts('file='); io.puts('name=') } if ENV['GITHUB_OUTPUT']
+  exit 0
+end
+
+# --- 2. attribute to a PR --------------------------------------------------------
+pr = nil
+pr_source = nil
+if pr_arg && pr_arg > 0
+  pr = pr_arg
+  pr_source = 'event'
+elsif ENV['GITHUB_EVENT_PATH'] && File.exist?(ENV['GITHUB_EVENT_PATH'])
+  ev = JSON.parse(File.read(ENV['GITHUB_EVENT_PATH'])) rescue {}
+  n = ev.dig('pull_request', 'number')
+  if n
+    pr = n.to_i
+    pr_source = 'event'
+  end
+end
+if pr.nil? && File.exist?(pr_result_file)
+  # The factory/fleet convention: the agent writes the PR/issue URL(s) it opened
+  # to pr-result.txt. The first pull URL is the PR this run CREATED — its spend
+  # is that PR's creation cost.
+  if (m = File.read(pr_result_file, encoding: 'UTF-8')[%r{/pull/(\d+)}, 1])
+    pr = m.to_i
+    pr_source = 'created'
+  end
+end
+records.each { |r| r['pr'] ||= pr; r['pr_source'] ||= pr_source if pr }
+
+# --- 3. consume: move to a reported file, hand the path to the uploader ----------
+reported = File.join(AIUsage.dir, "reported-#{Time.now.utc.strftime('%H%M%S')}-#{SecureRandom.hex(3)}.jsonl")
+File.open(reported, 'w') { |io| records.each { |r| io.puts(JSON.generate(r)) } }
+File.delete(src)
+if ENV['GITHUB_OUTPUT']
+  artifact = "ai-usage-#{ENV['GITHUB_RUN_ID'] || 'local'}-#{(ENV['GITHUB_JOB'] || 'job').gsub(/[^A-Za-z0-9_-]/, '_')}-#{SecureRandom.hex(3)}"
+  File.open(ENV['GITHUB_OUTPUT'], 'a') { |io| io.puts("file=#{reported}"); io.puts("name=#{artifact}") }
+end
+
+fmt_usd = ->(v) { format('$%.4f', v.to_f) }
+fmt_tok = ->(v) { v.to_i >= 10_000 ? "#{(v.to_i / 1000.0).round}k" : v.to_i.to_s }
+
+# --- 4. step summary --------------------------------------------------------------
+if ENV['GITHUB_STEP_SUMMARY']
+  total = records.sum { |r| r['cost_usd'].to_f }
+  lines = []
+  lines << '## 🤖 AI usage (this job)'
+  lines << ''
+  lines << '| role | model | turns | in | out | cache r/w | cost (API-equiv) | via |'
+  lines << '|---|---|---|---|---|---|---|---|'
+  records.each do |r|
+    t = r['tokens'] || {}
+    lines << "| #{r['agent'].to_s.empty? ? '—' : r['agent']} | #{r['model']} | #{r['num_turns'] || '—'} " \
+             "| #{fmt_tok.call(t['input'])} | #{fmt_tok.call(t['output'])} " \
+             "| #{fmt_tok.call(t['cache_read'])}/#{fmt_tok.call(t['cache_creation'])} " \
+             "| #{fmt_usd.call(r['cost_usd'])}#{r['cost_source'] == 'estimated' ? '*' : ''} | #{r['auth']} |"
+  end
+  lines << ''
+  # A failed call bills nothing, so it is invisible in the table above — spell
+  # out what the model refused, right where the operator is already looking.
+  records.select { |r| r['error'] }.each do |r|
+    e = r['error']
+    lines << "> ❌ **#{r['agent'].to_s.empty? ? 'AI call' : r['agent']} failed** " \
+             "(`#{e['subtype'].to_s.empty? ? "exit #{e['exit_code']}" : e['subtype']}`): #{e['message']}"
+    lines << ''
+  end
+  lines << "**Job total: #{fmt_usd.call(total)}** (API-equivalent#{records.any? { |r| r['cost_source'] == 'estimated' } ? '; * = estimated from _data/ai_pricing.yml' : ''})."
+  lines << ''
+  File.open(ENV['GITHUB_STEP_SUMMARY'], 'a') { |io| io.puts(lines.join("\n")) }
+end
+
+# --- 5. sticky PR comment (best-effort) --------------------------------------------
+repo = ENV['GITHUB_REPOSITORY'].to_s
+exit 0 if pr.nil? || repo.empty?
+unless system('gh --version > /dev/null 2>&1') && !(ENV['GH_TOKEN'].to_s + ENV['GITHUB_TOKEN'].to_s).empty?
+  warn '[usage_report] no gh/token — skipping the PR comment (records still in the artifact).'
+  exit 0
+end
+
+def gh_json(args)
+  out = IO.popen(['gh'] + args, err: %i[child out], &:read)
+  return nil unless $?.success?
+  JSON.parse(out)
+rescue StandardError
+  nil
+end
+
+# Find the existing sticky comment by MARKER (any author, any position).
+existing = nil
+page = 1
+loop do
+  batch = gh_json(['api', "repos/#{repo}/issues/#{pr}/comments?per_page=100&page=#{page}"])
+  break unless batch.is_a?(Array)
+  existing = batch.find { |c| c['body'].to_s.start_with?(MARKER) }
+  break if existing || batch.size < 100 || page >= 10
+  page += 1
+end
+
+# Merge this job's records into the comment's embedded blob (dedup by id).
+blob = { 'records' => [], 'folded' => nil }
+if existing && (m = existing['body'].to_s[/#{Regexp.escape(DATA_HEAD)}([A-Za-z0-9+\/=]+) -->/, 1])
+  blob = JSON.parse(m.unpack1('m')) rescue { 'records' => [], 'folded' => nil }
+end
+compact = ->(r) do
+  t = r['tokens'] || {}
+  { 'i' => r['id'], 't' => r['ts'], 'w' => r['workflow'], 'j' => r['job'], 'r' => r['run_id'],
+    'a' => r['agent'], 'm' => r['model'], 'ti' => t['input'].to_i, 'to' => t['output'].to_i,
+    'tr' => t['cache_read'].to_i, 'tc' => t['cache_creation'].to_i,
+    'c' => r['cost_usd'].to_f.round(6), 's' => r['cost_source'], 'au' => r['auth'],
+    'st' => r['status'], 'ps' => r['pr_source'] }
+end
+known = blob['records'].map { |r| r['i'] }
+records.each { |r| blob['records'] << compact.call(r) unless known.include?(r['id']) }
+blob['records'].sort_by! { |r| r['t'].to_s }
+while blob['records'].size > MAX_BLOB_RECORDS
+  old = blob['records'].shift
+  f = blob['folded'] ||= { 'n' => 0, 'c' => 0.0, 'ti' => 0, 'to' => 0 }
+  f['n'] += 1
+  f['c'] = (f['c'] + old['c'].to_f).round(6)
+  f['ti'] += old['ti'].to_i
+  f['to'] += old['to'].to_i
+end
+
+all      = blob['records']
+folded   = blob['folded']
+total    = all.sum { |r| r['c'].to_f } + (folded ? folded['c'].to_f : 0.0)
+creation = all.select { |r| r['ps'] == 'created' }.sum { |r| r['c'].to_f }
+downstream = total - creation
+estimated = all.any? { |r| r['s'] == 'estimated' }
+oauth_only = all.all? { |r| r['au'] == 'oauth' }
+
+body = []
+body << MARKER
+body << '## 🤖 AI usage & cost for this PR'
+body << ''
+body << "**Total: #{fmt_usd.call(total)} API-equivalent** across #{all.size + (folded ? folded['n'] : 0)} AI call(s) — " \
+        "creation #{fmt_usd.call(creation)}, reviews/fixes/checks #{fmt_usd.call(downstream)}."
+body << ''
+body << '| when (UTC) | workflow · job | role | model | out tok | cost |'
+body << '|---|---|---|---|---|---|'
+body << "| _earlier_ | _#{folded['n']} older call(s), folded_ | | | #{fmt_tok.call(folded['to'])} | #{fmt_usd.call(folded['c'])} |" if folded
+all.last(MAX_TABLE_ROWS).each do |r|
+  run_link = r['r'].to_s.empty? ? (r['w'].to_s.empty? ? 'local' : r['w']) : "[#{r['w']} · #{r['j']}](https://github.com/#{repo}/actions/runs/#{r['r']})"
+  body << "| #{r['t'].to_s[5, 11]} | #{run_link} | #{r['a'].to_s.empty? ? '—' : r['a']}#{r['ps'] == 'created' ? ' 🌱' : ''} " \
+          "| #{r['m']} | #{fmt_tok.call(r['to'])} | #{fmt_usd.call(r['c'])}#{r['s'] == 'estimated' ? '*' : ''} |"
+end
+body << "| | _…#{all.size - MAX_TABLE_ROWS} more in the ledger_ | | | | |" if all.size > MAX_TABLE_ROWS
+body << ''
+notes = ['🌱 = the run that opened this PR (creation cost).']
+notes << '\\* = estimated from `_data/ai_pricing.yml` (that path reports tokens, not dollars).' if estimated
+notes << (oauth_only ? 'All calls ran on Claude Code subscription auth (OAuth) — $0 marginal spend; the figure is what these tokens would bill at API list prices.' \
+                     : 'Some calls used a metered API key — those dollars are real.')
+notes << 'Updated automatically after every AI job; full history at [/docs/ai-usage/](https://lifehacker.dev/docs/ai-usage/).'
+body << notes.map { |n| "_#{n}_" }.join(' ')
+body << ''
+body << "#{DATA_HEAD}#{[JSON.generate(blob)].pack('m0')} -->"
+
+payload = JSON.generate('body' => body.join("\n"))
+tmp = File.join(AIUsage.dir, 'comment-payload.json')
+File.write(tmp, payload)
+ok =
+  if existing
+    system('gh', 'api', '-X', 'PATCH', "repos/#{repo}/issues/comments/#{existing['id']}", '--input', tmp, out: File::NULL, err: %i[child out])
+  else
+    system('gh', 'api', "repos/#{repo}/issues/#{pr}/comments", '--input', tmp, out: File::NULL, err: %i[child out])
+  end
+warn(ok ? "[usage_report] PR ##{pr} cost comment #{existing ? 'updated' : 'created'} (total #{fmt_usd.call(total)})." \
+        : "[usage_report] PR ##{pr} comment update failed (non-fatal; records are in the artifact).")
+exit 0

data/scripts/bin/audit-consumer

@@ -118,14 +118,35 @@ done
 
 CONSUMER_PATH="$(cd "$CONSUMER_PATH" && pwd)"
 
+# In --format json, stdout must be PURE JSON so `jq` / `json.load` can consume
+# it directly. The human-readable log lines are still useful, so send them to
+# stderr rather than dropping them. (Left on stdout, they made every --format
+# json run unparseable even after the trailing-comma fix.)
+if [[ "$FORMAT" == "json" ]]; then
+    info()    { echo -e "${BLUE}[INFO]${NC} $1" >&2; }
+    step()    { echo -e "${CYAN}[STEP]${NC} $1" >&2; }
+    success() { echo -e "${GREEN}[SUCCESS]${NC} $1" >&2; }
+    warn()    { echo -e "${YELLOW}[WARNING]${NC} $1" >&2; }
+fi
+
 # ---------------------------------------------------------------------------
 step "Auditing consumer: $CONSUMER_PATH"
 
-# Detect or confirm mode
+# CONSUMER_ROOT holds the config/override files; CONSUMER_PATH is where the
+# theme-shadowing files actually live. They differ when the consumer sets
+# Jekyll's `source:` (zer0-pages keeps its whole site tree under `pages/`).
+CONSUMER_ROOT="$CONSUMER_PATH"
+CONSUMER_SOURCE_REL=$(detect_consumer_source "$CONSUMER_ROOT")
+if [[ -n "$CONSUMER_SOURCE_REL" && -d "$CONSUMER_ROOT/$CONSUMER_SOURCE_REL" ]]; then
+    CONSUMER_PATH="$CONSUMER_ROOT/$CONSUMER_SOURCE_REL"
+    info "Jekyll source: $CONSUMER_SOURCE_REL/ — scanning there, not the repo root"
+fi
+
+# Detect or confirm mode (from the repo root, where _config.yml lives)
 if [[ -n "$MODE_OVERRIDE" ]]; then
     MODE="$MODE_OVERRIDE"
 else
-    MODE=$(detect_consumer_mode "$CONSUMER_PATH")
+    MODE=$(detect_consumer_mode "$CONSUMER_ROOT")
     info "Detected mode: $MODE"
 fi
 
@@ -133,7 +154,7 @@ fi
 if [[ -n "$THEME_PATH_OVERRIDE" ]]; then
     RESOLVED_THEME="$THEME_PATH_OVERRIDE"
 else
-    RESOLVED_THEME=$(resolve_theme_path "$MODE" "$CONSUMER_PATH" "$THEME_ROOT")
+    RESOLVED_THEME=$(resolve_theme_path "$MODE" "$CONSUMER_ROOT" "$THEME_ROOT")
 fi
 
 if [[ -z "$RESOLVED_THEME" || ! -d "$RESOLVED_THEME" ]]; then
@@ -149,7 +170,10 @@ if [[ ! -f "$MANIFEST" ]]; then
 fi
 
 # Load overrides manifest from consumer
-OVERRIDES_FILE="$CONSUMER_PATH/.theme-overrides.yml"
+# Declared overrides sit next to _config.yml at the repo root; fall back to the
+# source dir so either placement works.
+OVERRIDES_FILE="$CONSUMER_ROOT/.theme-overrides.yml"
+[[ -f "$OVERRIDES_FILE" ]] || OVERRIDES_FILE="$CONSUMER_PATH/.theme-overrides.yml"
 OVERRIDE_PATHS_TMP=$(mktemp)
 trap 'rm -f "$OVERRIDE_PATHS_TMP"' EXIT
 
@@ -190,8 +214,14 @@ if [[ ${#THEMABLE_DIRS[@]} -eq 0 ]]; then
     THEMABLE_DIRS=("_layouts" "_includes" "_sass" "assets/css" "assets/js")
 fi
 if [[ ${#REQUIRED_PLUGIN_FILES[@]} -eq 0 && ${#OPTIONAL_PLUGIN_FILES[@]} -eq 0 ]]; then
-    REQUIRED_PLUGIN_FILES=("_plugins/obsidian_links.rb")
-    OPTIONAL_PLUGIN_FILES=("_plugins/admin_page_urls.rb" "_plugins/content_statistics_generator.rb" "_plugins/theme_version.rb")
+    # No manifest at all. Nothing is genuinely required (GitHub Pages loads no
+    # local plugins), so every known plugin is offered as optional.
+    OPTIONAL_PLUGIN_FILES=(
+        "_plugins/obsidian_links.rb"
+        "_plugins/admin_page_urls.rb"
+        "_plugins/content_statistics_generator.rb"
+        "_plugins/theme_version.rb"
+    )
 fi
 
 # ---------------------------------------------------------------------------
@@ -316,7 +346,9 @@ fi
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------
-[[ "$FORMAT" == "json" ]] && echo ']}'
+# Entries are printed without a trailing newline (see print_classification),
+# so close the array on its own line.
+[[ "$FORMAT" == "json" ]] && printf '\n]}\n'
 
 if [[ "$FORMAT" == "text" ]]; then
     echo ""

data/scripts/bin/giscus-discussions

@@ -6,6 +6,7 @@
 # `giscus-conversation` skill drives to build conversations from page comments.
 #
 # Subcommands:
+#   doctor       Verify the comment chain end-to-end (app installed, IDs match)
 #   categories   List the repo's discussion categories + node IDs (setup helper)
 #   list         List discussions in the configured Giscus category
 #   thread       Print a discussion's full conversation (comments + replies)
@@ -72,14 +73,22 @@ resolve_category() {
 owner_of() { printf '%s' "${1%%/*}"; }
 name_of()  { printf '%s' "${1##*/}"; }
 
-# Normalize a page path so it matches a Giscus pathname-mapped discussion title.
+# Normalize a page path into the *Giscus term* — the string Giscus actually
+# searches discussion titles for under data-mapping="pathname".
+#
+# Giscus uses location.pathname with the leading slash STRIPPED. Verified live:
+# /posts/2025/01/21/remote-work-revolution/ produces a widget iframe with
+#   term=posts%2F2025%2F01%2F21%2Fremote-work-revolution%2F
+# This previously prepended a slash instead, so `seed` created titles Giscus
+# would never match, and `--page` lookups missed every thread Giscus itself
+# created. Callers may still pass a leading slash or a full URL.
 normalize_page() {
     local p="$1"
     if [[ "$p" == *"://"* ]]; then
         p="${p#*://}"   # strip scheme
-        p="/${p#*/}"    # strip host, keep path with a leading slash
+        p="${p#*/}"     # strip host, keep the path
     fi
-    [[ "$p" != /* ]] && p="/$p"
+    p="${p#/}"          # Giscus's pathname term carries no leading slash
     printf '%s' "$p"
 }
 
@@ -95,15 +104,26 @@ repo_node_id() {
       --jq '.data.repository.id'
 }
 
-# Find a discussion number whose title equals the (normalized) page path.
-# Echoes the number, or nothing if not found.
+# Find a discussion number whose title matches the page. Echoes the number, or
+# nothing if not found.
+#
+# Matches four title spellings so lookups work against BOTH threads Giscus
+# created (its own term: no leading slash) and any hand-made or legacy thread
+# titled with a leading slash. Paginates: the previous version declared $after
+# and pageInfo but never used them, so on a site with more than 100 discussions
+# it silently failed to find anything past the first page.
 discussion_number_for_page() {
-    local page; page="$(normalize_page "$1")"
-    local page_noslash="${page%/}"
-    gh api graphql -f query='
-      query($owner:String!,$name:String!,$categoryId:ID,$after:String){
+    local term; term="$(normalize_page "$1")"
+    # Match four spellings so lookups work against BOTH threads Giscus created
+    # (its own term: no leading slash) and hand-made/legacy threads titled with
+    # one. --paginate walks every page: the previous version declared $after and
+    # pageInfo but never used them, so on a site with more than 100 discussions
+    # it silently failed to find anything past the first page.
+    local matches
+    matches="$(gh api graphql --paginate -f query='
+      query($owner:String!,$name:String!,$categoryId:ID,$endCursor:String){
         repository(owner:$owner,name:$name){
-          discussions(first:100,after:$after,categoryId:$categoryId){
+          discussions(first:100,after:$endCursor,categoryId:$categoryId){
             nodes{ number title }
             pageInfo{ hasNextPage endCursor }
           }
@@ -111,8 +131,16 @@ discussion_number_for_page() {
       }' -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
          -f categoryId="$CATEGORY_ID" \
       --jq ".data.repository.discussions.nodes[]
-            | select(.title == \"$page\" or .title == \"$page_noslash\")
-            | .number" | head -1
+            | select(.title == \"${term}\"
+                  or .title == \"${term%/}\"
+                  or .title == \"/${term}\"
+                  or .title == \"/${term%/}\")
+            | .number" 2>/dev/null)"
+    # First match only. Deliberately NOT `| head -1` on the pipeline: head
+    # closes the pipe early, gh dies on SIGPIPE, and `set -o pipefail` then
+    # aborts the whole script inside the surrounding command substitution.
+    local nl=$'\n'
+    printf '%s' "${matches%%${nl}*}"
 }
 
 discussion_node_id() {
@@ -260,7 +288,12 @@ resolve_number_arg() {
     elif [[ -n "$page" ]]; then
         resolve_category
         NUMBER="$(discussion_number_for_page "$page")"
-        [[ -z "$NUMBER" ]] && error "No discussion found for page '$page'. Seed one with: $0 seed --page '$page' --title ... --body ..."
+        # `if`, not `[[ ... ]] && error`: as the last statement in this branch a
+        # false test returns 1, which `set -e` turns into a silent script abort
+        # on the SUCCESS path.
+        if [[ -z "$NUMBER" ]]; then
+            error "No discussion found for page '$page'. Seed one with: $0 seed --page '$page' --title ... --body ..."
+        fi
     else
         error "Provide --number N, --url URL, or --page PATH."
     fi
@@ -401,7 +434,9 @@ cmd_post() {
     elif [[ -n "$page" ]]; then
         resolve_category
         NUMBER="$(discussion_number_for_page "$page")"
-        [[ -z "$NUMBER" ]] && error "No discussion for page '$page'. Seed one first: $0 seed --page '$page' ..."
+        if [[ -z "$NUMBER" ]]; then
+            error "No discussion for page '$page'. Seed one first: $0 seed --page '$page' ..."
+        fi
     else
         error "post: provide --number N, --url URL, or --page PATH."
     fi
@@ -448,6 +483,167 @@ cmd_post() {
     success "Comment posted to discussion #$NUMBER"
 }
 
+# ---------------------------------------------------------------------------
+# Subcommand: doctor (verify the whole comment chain actually works)
+# ---------------------------------------------------------------------------
+
+# Why this exists: every other check in this repo is static. The core test
+# validates _config.yml keys and the include's Liquid; the Playwright spec stubs
+# giscus.app out entirely. All of them pass with a 100% broken widget, because
+# the two things that actually break comments in practice live on GitHub's side,
+# not in any file here:
+#   1. the giscus GitHub App not being installed on the repo
+#   2. a data-repo-id / data-category-id that doesn't belong to this repo
+# `doctor` asks Giscus itself, which is the only authoritative answer.
+
+# Read a scalar from the giscus block of _config.yml (same block-scoping as
+# config_category_id, which only handles data-category-id).
+config_giscus_key() {
+    local key="$1"
+    [[ -f "$CONFIG_FILE" ]] || return 0
+    # Block-scoped to the top-level `giscus:` mapping, then strip the key, any
+    # trailing comment, and surrounding quotes (\047 is awk for a single quote).
+    awk -v k="${key}:" '
+        /^giscus:/ { f=1; next }
+        f && /^[^[:space:]#]/ { f=0 }
+        f && $1 == k {
+            sub(/^[[:space:]]*[^:]+:[[:space:]]*/, "")
+            sub(/[[:space:]]+#.*$/, "")
+            gsub(/^["\047]+|["\047]+[[:space:]]*$/, "")
+            print
+            exit
+        }' "$CONFIG_FILE"
+}
+
+# Non-fatal error: report and let the caller accumulate failures. common.sh's
+# error() exits, which would stop doctor at the first problem instead of
+# reporting every one.
+doctor_fail() { printf '\033[0;31m[FAIL]\033[0m %s\n' "$*" >&2; }
+
+# One graphql call, one field out — avoids needing a standalone jq.
+gql_repo_field() {
+    gh api graphql -f query="$1" \
+        -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
+        --jq "$2" 2>/dev/null
+}
+
+REPO_Q='
+  query($owner:String!,$name:String!){
+    repository(owner:$owner,name:$name){
+      id isPrivate hasDiscussionsEnabled
+      discussionCategories(first:50){ nodes{ id name } }
+    }
+  }'
+
+cmd_doctor() {
+    local category_name=""
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --repo) REPO_NWO="$2"; shift 2 ;;
+            --category-id) CATEGORY_ID="$2"; shift 2 ;;
+            --category) category_name="$2"; shift 2 ;;
+            *) error "doctor: unknown option '$1'" ;;
+        esac
+    done
+    resolve_repo
+    require_command gh "install: https://cli.github.com/"
+    require_command curl "install: https://curl.se/"
+
+    local failed=0
+    info "Checking the Giscus comment chain for $REPO_NWO"
+
+    # --- 1. Repo-side facts, straight from the GitHub API -------------------
+    local real_repo_id is_private discussions_on
+    real_repo_id="$(gql_repo_field "$REPO_Q" '.data.repository.id')"
+    [[ -z "$real_repo_id" ]] && error "Could not query $REPO_NWO via gh. Check the repo name and \`gh auth status\`."
+    is_private="$(gql_repo_field "$REPO_Q" '.data.repository.isPrivate')"
+    discussions_on="$(gql_repo_field "$REPO_Q" '.data.repository.hasDiscussionsEnabled')"
+
+    if [[ "$is_private" == "false" ]]; then
+        success "Repository is public"
+    else
+        doctor_fail "Repository is PRIVATE — visitors cannot read the discussions"; failed=1
+    fi
+
+    if [[ "$discussions_on" == "true" ]]; then
+        success "Discussions are enabled"
+    else
+        doctor_fail "Discussions are NOT enabled (Settings → General → Features → Discussions)"; failed=1
+    fi
+
+    # --- 2. Config IDs must belong to THIS repo ----------------------------
+    local cfg_repo_id cfg_category_id cfg_enabled
+    cfg_repo_id="$(config_giscus_key 'data-repo-id')"
+    cfg_category_id="${CATEGORY_ID:-$(config_giscus_key 'data-category-id')}"
+    cfg_enabled="$(config_giscus_key 'enabled')"
+
+    if [[ "$cfg_enabled" == "true" ]]; then
+        success "_config.yml has giscus.enabled: true"
+    else
+        doctor_fail "_config.yml has giscus.enabled: '${cfg_enabled:-unset}' — comments will not render"
+        failed=1
+    fi
+
+    if [[ -z "$cfg_repo_id" ]]; then
+        doctor_fail "_config.yml is missing giscus.data-repo-id"; failed=1
+    elif [[ "$cfg_repo_id" == "$real_repo_id" ]]; then
+        success "data-repo-id matches $REPO_NWO ($real_repo_id)"
+    else
+        doctor_fail "data-repo-id '$cfg_repo_id' does NOT belong to $REPO_NWO (expected '$real_repo_id'). Forked without regenerating it?"
+        failed=1
+    fi
+
+    # Resolve the configured category id to a name (proves it exists on this repo).
+    local cat_name=""
+    if [[ -n "$cfg_category_id" ]]; then
+        cat_name="$(gql_repo_field "$REPO_Q" \
+            ".data.repository.discussionCategories.nodes[] | select(.id == \"${cfg_category_id}\") | .name")"
+    fi
+    if [[ -n "$cat_name" ]]; then
+        success "data-category-id resolves to the '$cat_name' category"
+    else
+        doctor_fail "data-category-id '${cfg_category_id:-unset}' is not a category on $REPO_NWO (see: $0 categories)"
+        failed=1
+    fi
+    [[ -n "$category_name" ]] && cat_name="$category_name"
+
+    # --- 3. The authoritative check: ask Giscus ----------------------------
+    # Only Giscus knows whether its GitHub App is installed on the repo. No
+    # amount of config inspection can substitute for this call.
+    local api_out
+    api_out="$(curl -s -m 20 -G https://giscus.app/api/discussions \
+        --data-urlencode "repo=$REPO_NWO" \
+        --data-urlencode "category=${cat_name:-Announcements}" \
+        --data-urlencode "term=/" \
+        -d "number=0&strict=true&first=1" 2>/dev/null || true)"
+
+    if [[ -z "$api_out" ]]; then
+        warn "Could not reach giscus.app (offline?) — app-installation check SKIPPED"
+    elif printf '%s' "$api_out" | grep -q 'giscus is not installed'; then
+        doctor_fail "The giscus GitHub App is NOT installed on $REPO_NWO — comments are broken sitewide."
+        info "    Install: https://github.com/apps/giscus → Configure → grant access to $REPO_NWO"
+        failed=1
+    elif printf '%s' "$api_out" | grep -qi '"error"'; then
+        local msg
+        msg="$(printf '%s' "$api_out" | sed -E 's/.*"error"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/')"
+        # "Discussion not found" is the healthy answer for a page nobody has
+        # commented on yet — Giscus creates the thread on the first comment.
+        if printf '%s' "$msg" | grep -qi 'not found'; then
+            success "Giscus app is installed (no thread for '/' yet — created on first comment)"
+        else
+            doctor_fail "Giscus reported: $msg"; failed=1
+        fi
+    else
+        success "Giscus app is installed and serving this repo"
+    fi
+
+    echo
+    if [[ "$failed" -ne 0 ]]; then
+        error "Giscus chain is BROKEN — comments will not work for visitors."
+    fi
+    success "Giscus chain is healthy — comments will render for visitors."
+}
+
 # ---------------------------------------------------------------------------
 # Usage / dispatch
 # ---------------------------------------------------------------------------
@@ -460,6 +656,7 @@ USAGE:
     ./scripts/bin/giscus-discussions <subcommand> [options]
 
 SUBCOMMANDS:
+    doctor                     Verify the whole chain works (app installed, IDs match)
     categories                 List discussion categories + node IDs (setup helper)
     list [--json]              List discussions in the Giscus category
     thread <target> [--json]   Show a discussion's full conversation
@@ -481,6 +678,7 @@ ENVIRONMENT:
     GISCUS_CATEGORY_ID         Default --category-id
 
 EXAMPLES:
+    ./scripts/bin/giscus-discussions doctor
     ./scripts/bin/giscus-discussions categories
     ./scripts/bin/giscus-discussions list
     ./scripts/bin/giscus-discussions thread --page /posts/2025/01/21/remote-work-revolution/
@@ -497,6 +695,7 @@ main() {
     [[ $# -gt 0 ]] && shift || true
     case "$sub" in
         categories) cmd_categories "$@" ;;
+        doctor)     cmd_doctor "$@" ;;
         list)       cmd_list "$@" ;;
         thread)     cmd_thread "$@" ;;
         draft)      cmd_draft "$@" ;;