@neocage/council 1.3.0

package/scripts/council-simulation-checklist.sh

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${REPO_DIR}"
+
+echo "== Council Simulation Checklist =="
+
+pass() { echo "[PASS] $1"; }
+fail() { echo "[FAIL] $1"; exit 1; }
+warn() { echo "[WARN] $1"; }
+
+# --- File existence checks ---
+
+[[ -f "SKILL.md" ]] || fail "SKILL.md is missing"
+pass "SKILL.md exists"
+[[ -f "SKILL.codex.md" ]] || fail "SKILL.codex.md is missing"
+pass "SKILL.codex.md exists"
+[[ -f "SKILL.gemini.md" ]] || fail "SKILL.gemini.md is missing"
+pass "SKILL.gemini.md exists"
+
+if compgen -G "agents/council-*.md" >/dev/null; then
+  agent_count=$(compgen -G "agents/council-*.md" | wc -l | tr -d ' ')
+  pass "Agent definitions found (count=${agent_count})"
+else
+  fail "No agent definitions found under agents/council-*.md"
+fi
+
+[[ -f "configs/provider-model-slots.example.yaml" ]] || fail "configs/provider-model-slots.example.yaml is missing"
+pass "Provider/model slot template exists"
+
+# --- Plugin manifest checks ---
+
+[[ -f ".claude-plugin/plugin.json" ]] || fail ".claude-plugin/plugin.json is missing"
+[[ -f ".claude-plugin/marketplace.json" ]] || fail ".claude-plugin/marketplace.json is missing"
+[[ -e "skills/council/SKILL.md" ]] || fail "skills/council/SKILL.md (plugin skill path) is missing or a broken symlink"
+pass "Plugin manifests and skill path present"
+
+changelog_version=$(sed -nE 's/^## \[([0-9]+\.[0-9]+\.[0-9]+)\].*/\1/p' CHANGELOG.md | head -1)
+plugin_version=$(sed -nE 's/.*"version": "([0-9]+\.[0-9]+\.[0-9]+)".*/\1/p' .claude-plugin/plugin.json | head -1)
+marketplace_version=$(sed -nE 's/.*"version": "([0-9]+\.[0-9]+\.[0-9]+)".*/\1/p' .claude-plugin/marketplace.json | head -1)
+if [[ "$plugin_version" != "$changelog_version" ]] || [[ "$marketplace_version" != "$changelog_version" ]]; then
+  fail "Version drift: CHANGELOG=${changelog_version} plugin.json=${plugin_version} marketplace.json=${marketplace_version} — bump the manifests when releasing"
+fi
+pass "Plugin manifest versions match CHANGELOG (${changelog_version})"
+
+[[ -f "CLAUDE.md" ]] || warn "CLAUDE.md is missing (recommended for project conventions)"
+
+# --- SKILL.md content checks ---
+
+grep -q "exploration-orthogonal" SKILL.md || fail "exploration-orthogonal profile missing in SKILL.md"
+pass "exploration-orthogonal profile documented in SKILL.md"
+
+grep -q "execution-lean" SKILL.md || fail "execution-lean profile missing in SKILL.md"
+pass "execution-lean profile documented in SKILL.md"
+
+grep -q -- "--models" SKILL.md || fail "--models flag missing in SKILL.md"
+pass "--models flag documented in SKILL.md"
+
+grep -q -- "--quick" SKILL.md || fail "--quick flag missing in SKILL.md"
+pass "--quick mode documented in SKILL.md"
+
+grep -q -- "--duo" SKILL.md || fail "--duo flag missing in SKILL.md"
+pass "--duo mode documented in SKILL.md"
+
+grep -q "CHECKPOINT" SKILL.md || fail "Execution checkpoints missing in SKILL.md"
+pass "Execution checkpoints present in SKILL.md"
+
+grep -q "VERIFY" SKILL.md || fail "Verification steps missing in SKILL.md"
+pass "Verification steps present in SKILL.md"
+
+# Round 2 anonymization (issue #17) — protect against silent regression
+grep -q "ANONYMIZED" SKILL.md || fail "Round 2 anonymization missing in SKILL.md (issue #17)"
+grep -q "Member A" SKILL.md || fail "Member-label vocabulary missing in SKILL.md (issue #17)"
+pass "Round 2 anonymization wired in SKILL.md"
+
+grep -q "anonymiz" SKILL.codex.md || fail "Round 2 anonymization missing in SKILL.codex.md (issue #17)"
+pass "Round 2 anonymization wired in SKILL.codex.md"
+
+# Anti-conformity directive (issue #19) — must be in every Round 2 prompt
+ac_count_skill=$(grep -c "Anti-conformity directive" SKILL.md || true)
+if [[ "$ac_count_skill" -lt 3 ]]; then
+  fail "Anti-conformity directive missing from one or more Round 2 prompts in SKILL.md (issue #19; expected ≥3 occurrences, found ${ac_count_skill})"
+fi
+pass "Anti-conformity directive present in all 3 Round 2 prompts in SKILL.md"
+
+grep -q "Anti-conformity directive" SKILL.codex.md || fail "Anti-conformity directive missing in SKILL.codex.md (issue #19)"
+pass "Anti-conformity directive present in SKILL.codex.md"
+
+# Chairman role (issue #18) — must be wired into STEP 1.7, STEP 7, flags, and Codex
+grep -q "STEP 1.7" SKILL.md || fail "Chairman selection step missing in SKILL.md (issue #18)"
+grep -q -- "--chairman" SKILL.md || fail "--chairman flag missing in SKILL.md (issue #18)"
+grep -q "CHAIRMAN" SKILL.md || fail "Chairman synthesis step missing in SKILL.md (issue #18)"
+pass "Chairman role wired in SKILL.md (STEP 1.7 + --chairman flag + synthesis step)"
+
+grep -q -i "chairman" SKILL.codex.md || fail "Chairman role missing in SKILL.codex.md (issue #18)"
+pass "Chairman role wired in SKILL.codex.md"
+
+grep -q "chairman_defaults" configs/auto-route-defaults.yaml || fail "chairman_defaults block missing in auto-route-defaults.yaml (issue #18)"
+pass "Chairman defaults configured in auto-route-defaults.yaml"
+
+# Verdict actionability sections (issue #21)
+grep -q "Acceptable Compromises" SKILL.md || fail "Acceptable Compromises section missing in SKILL.md (issue #21)"
+grep -q "Kill Criteria" SKILL.md || fail "Kill Criteria section missing in SKILL.md (issue #21)"
+grep -q "Concrete Next Step" SKILL.md || fail "Concrete Next Step section missing in SKILL.md (issue #21)"
+pass "Verdict actionability sections present in SKILL.md (Acceptable Compromises / Kill Criteria / Concrete Next Step)"
+
+grep -q "Acceptable Compromises" SKILL.codex.md || fail "Acceptable Compromises missing in SKILL.codex.md (issue #21)"
+grep -q "Kill Criteria" SKILL.codex.md || fail "Kill Criteria missing in SKILL.codex.md (issue #21)"
+grep -q "Concrete Next Step" SKILL.codex.md || fail "Concrete Next Step missing in SKILL.codex.md (issue #21)"
+pass "Verdict actionability sections present in SKILL.codex.md"
+
+# OpenAI-compatible API archetype (issue #16) — must be wired in dispatch + routing
+grep -q "openai_compatible_api" SKILL.md || fail "openai_compatible_api archetype missing in SKILL.md (issue #16)"
+grep -q "base_url" SKILL.md || fail "base_url handling missing in SKILL.md (issue #16)"
+grep -q "api_key_env" SKILL.md || fail "api_key_env handling missing in SKILL.md (issue #16)"
+pass "openai_compatible_api archetype wired in SKILL.md (dispatch + base_url + api_key_env)"
+
+grep -q "openai_compatible_api\|openai-compatible\|OpenAI-Compatible" SKILL.codex.md || fail "openai_compatible_api archetype missing in SKILL.codex.md (issue #16)"
+pass "openai_compatible_api archetype wired in SKILL.codex.md"
+
+# Session Metadata schema (issue #7 Phase 1)
+grep -q "Session Metadata" SKILL.md || fail "Session Metadata block missing in SKILL.md (issue #7)"
+grep -q "schema_version: 1" SKILL.md || fail "schema_version: 1 marker missing in SKILL.md Session Metadata (issue #7)"
+pass "Session Metadata schema wired in SKILL.md"
+
+grep -q "Session Metadata\|session metadata\|session_metadata" SKILL.codex.md || fail "Session Metadata missing in SKILL.codex.md (issue #7)"
+pass "Session Metadata referenced in SKILL.codex.md"
+
+# --- SKILL.gemini.md parity checks ---
+# The Gemini variant is the least-exercised of the three coordinator files and
+# is exactly where feature drift shipped once before. Every protocol feature
+# checked for codex above is checked for gemini here.
+
+grep -q "anonymiz" SKILL.gemini.md || fail "Round 2 anonymization missing in SKILL.gemini.md (issue #17)"
+pass "Round 2 anonymization wired in SKILL.gemini.md"
+
+grep -q "Anti-conformity directive" SKILL.gemini.md || fail "Anti-conformity directive missing in SKILL.gemini.md (issue #19)"
+pass "Anti-conformity directive present in SKILL.gemini.md"
+
+grep -q -i "chairman" SKILL.gemini.md || fail "Chairman role missing in SKILL.gemini.md (issue #18)"
+pass "Chairman role wired in SKILL.gemini.md"
+
+grep -q "Acceptable Compromises" SKILL.gemini.md || fail "Acceptable Compromises missing in SKILL.gemini.md (issue #21)"
+grep -q "Kill Criteria" SKILL.gemini.md || fail "Kill Criteria missing in SKILL.gemini.md (issue #21)"
+grep -q "Concrete Next Step" SKILL.gemini.md || fail "Concrete Next Step missing in SKILL.gemini.md (issue #21)"
+pass "Verdict actionability sections present in SKILL.gemini.md"
+
+grep -q "openai_compatible_api\|openai-compatible\|OpenAI-Compatible" SKILL.gemini.md || fail "openai_compatible_api archetype missing in SKILL.gemini.md (issue #16)"
+pass "openai_compatible_api archetype wired in SKILL.gemini.md"
+
+grep -q "Session Metadata\|session metadata\|session_metadata" SKILL.gemini.md || fail "Session Metadata missing in SKILL.gemini.md (issue #7)"
+pass "Session Metadata referenced in SKILL.gemini.md"
+
+# --- Structured stance / weighted tally parity (PR #36) ---
+# All three coordinator files must carry the STANCE line, the Vote Tally
+# verdict field, and the 1.5x domain-weight seat. This is the check that
+# would have caught the Gemini regression.
+
+for skill_file in SKILL.md SKILL.codex.md SKILL.gemini.md; do
+  grep -q "STANCE:" "${skill_file}" || fail "Structured STANCE line missing in ${skill_file} (PR #36)"
+  grep -q "Vote Tally" "${skill_file}" || fail "Vote Tally verdict field missing in ${skill_file} (PR #36)"
+  grep -q "1\.5" "${skill_file}" || fail "1.5x domain-weight seat missing in ${skill_file} (PR #36)"
+  grep -q "2/3" "${skill_file}" || fail "2/3 consensus threshold missing in ${skill_file} (PR #36)"
+done
+pass "Structured stance + weighted tally present in all three SKILL files"
+
+# --- Agent structure checks ---
+
+required_sections=("Identity" "Grounding Protocol" "Analytical Method" "What You See" "What You Tend to Miss" "When Deliberating" "Output Format (Council Round 2)" "Output Format (Standalone)")
+
+agent_structure_ok=true
+for agent_file in agents/council-*.md; do
+  agent_name=$(basename "${agent_file}" .md)
+  for section in "${required_sections[@]}"; do
+    if ! grep -q "## ${section}" "${agent_file}" 2>/dev/null; then
+      # Some sections use slightly different headers, try partial match
+      section_word=$(echo "${section}" | awk '{print $1}')
+      if ! grep -qi "${section_word}" "${agent_file}" 2>/dev/null; then
+        warn "${agent_name}: missing section '${section}'"
+        agent_structure_ok=false
+      fi
+    fi
+  done
+done
+
+if [[ "${agent_structure_ok}" == true ]]; then
+  pass "All agents have consistent section structure"
+else
+  warn "Some agents have inconsistent section structure (see warnings above)"
+fi
+
+# --- Grounding protocol placement check ---
+
+grounding_early=true
+for agent_file in agents/council-*.md; do
+  agent_name=$(basename "${agent_file}" .md)
+  grounding_line=$(grep -n "## Grounding Protocol" "${agent_file}" 2>/dev/null | head -1 | cut -d: -f1 || echo "999")
+  method_line=$(grep -n "## Analytical Method" "${agent_file}" 2>/dev/null | head -1 | cut -d: -f1 || echo "0")
+  if [[ "${grounding_line}" -gt "${method_line}" ]] && [[ "${method_line}" -gt 0 ]]; then
+    warn "${agent_name}: Grounding Protocol appears after Analytical Method (should be before)"
+    grounding_early=false
+  fi
+done
+
+if [[ "${grounding_early}" == true ]]; then
+  pass "Grounding protocols placed before Analytical Method in all agents"
+fi
+
+# --- Triad member validation ---
+
+for member_name in aristotle socrates feynman ada sun-tzu machiavelli aurelius lao-tzu torvalds musashi watts karpathy sutskever kahneman meadows munger taleb rams; do
+  if [[ ! -f "agents/council-${member_name}.md" ]]; then
+    fail "Missing agent file for triad member: council-${member_name}.md"
+  fi
+done
+pass "All triad member agent files present"
+
+# --- Verdict template dedup check ---
+
+if grep -q "^{" demos/verdict-template.md 2>/dev/null; then
+  warn "demos/verdict-template.md still contains template placeholders (should point to SKILL.md)"
+fi
+pass "Verdict template dedup check done"
+
+# --- Auto-routing checks ---
+
+[[ -f "scripts/detect-providers.sh" ]] || fail "scripts/detect-providers.sh is missing"
+[[ -x "scripts/detect-providers.sh" ]] || fail "scripts/detect-providers.sh is not executable"
+pass "detect-providers.sh exists and is executable"
+
+if detect_output="$(bash scripts/detect-providers.sh 2>/dev/null)"; then
+  if echo "$detect_output" | grep -q '"provider_count"'; then
+    pass "detect-providers.sh produces valid JSON"
+  else
+    fail "detect-providers.sh output missing provider_count field"
+  fi
+else
+  fail "detect-providers.sh exited with error"
+fi
+
+[[ -f "configs/auto-route-defaults.yaml" ]] || fail "configs/auto-route-defaults.yaml is missing"
+pass "Auto-route defaults config exists"
+
+grep -q -- "--no-auto-route" SKILL.md || fail "--no-auto-route flag missing in SKILL.md"
+pass "--no-auto-route flag documented in SKILL.md"
+
+grep -q -- "--dry-route" SKILL.md || fail "--dry-route flag missing in SKILL.md"
+pass "--dry-route flag documented in SKILL.md"
+
+affinity_count=0
+for agent_file in agents/council-*.md; do
+  if grep -q "provider_affinity" "$agent_file" 2>/dev/null; then
+    ((affinity_count+=1))
+  fi
+done
+if [[ "$affinity_count" -eq "$agent_count" ]]; then
+  pass "All agents have provider_affinity in frontmatter"
+else
+  warn "Only ${affinity_count}/${agent_count} agents have provider_affinity"
+fi
+
+reasoning_method_count=0
+for agent_file in agents/council-*.md; do
+  if grep -q "reasoning_method" "$agent_file" 2>/dev/null; then
+    ((reasoning_method_count+=1))
+  fi
+done
+if [[ "$reasoning_method_count" -eq "$agent_count" ]]; then
+  pass "All agents have reasoning_method in frontmatter"
+else
+  warn "Only ${reasoning_method_count}/${agent_count} agents have reasoning_method"
+fi
+
+# --- Install script checks ---
+
+if command -v shellcheck >/dev/null 2>&1; then
+  shellcheck install.sh
+  pass "shellcheck passed for install.sh"
+else
+  warn "shellcheck not installed; skipped"
+fi
+
+TMP_LOG_DIR="$(mktemp -d)"
+trap 'rm -rf "${TMP_LOG_DIR}"' EXIT
+
+./install.sh --dry-run >"${TMP_LOG_DIR}/dry-run.log"
+pass "install.sh --dry-run completed"
+
+grep -q "Installed .* council agents" "${TMP_LOG_DIR}/dry-run.log" || fail "install dry-run output missing agent install summary"
+pass "install summary output present"
+
+./install.sh --dry-run --copy-configs >"${TMP_LOG_DIR}/dry-run-configs.log"
+pass "install.sh --dry-run --copy-configs completed"
+
+grep -q "Installed .* config files" "${TMP_LOG_DIR}/dry-run-configs.log" || fail "copy-configs dry-run output missing config install summary"
+pass "config summary output present"
+
+./install.sh --dry-run --codex >"${TMP_LOG_DIR}/dry-run-codex.log"
+pass "install.sh --dry-run --codex completed"
+
+grep -q "Installed Codex skill to" "${TMP_LOG_DIR}/dry-run-codex.log" || fail "codex dry-run output missing Codex skill summary"
+pass "Codex install summary output present"
+
+./install.sh --dry-run --gemini >"${TMP_LOG_DIR}/dry-run-gemini.log"
+pass "install.sh --dry-run --gemini completed"
+
+grep -q "gemini-extension.json" "${TMP_LOG_DIR}/dry-run-gemini.log" || fail "gemini dry-run output missing gemini-extension.json manifest step"
+pass "Gemini install manifest step present"
+
+echo
+echo "Checklist complete."

package/scripts/detect-providers.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Council of Cognitive Excellence — Provider Detection Script
+# Detects available LLM providers and outputs structured JSON to stdout.
+# Usage: ./scripts/detect-providers.sh
+
+TIMEOUT_SECONDS=5
+
+# --- Helper functions ---
+
+json_provider() {
+  local name="$1" available="$2" exec_method="$3" binary="$4" models="$5"
+  printf '{"name":"%s","available":%s,"exec_method":"%s","binary":"%s","models":[%s]}' \
+    "$name" "$available" "$exec_method" "$binary" "$models"
+}
+
+check_command() {
+  command -v "$1" 2>/dev/null || echo ""
+}
+
+# macOS-compatible timeout using perl (no coreutils required)
+run_with_timeout() {
+  perl -e '
+    use POSIX ":sys_wait_h";
+    my $timeout = shift @ARGV;
+    my $pid = fork();
+    if ($pid == 0) { exec @ARGV; exit 1; }
+    my $elapsed = 0;
+    while ($elapsed < $timeout) {
+      if (waitpid($pid, WNOHANG) > 0) { exit ($? >> 8); }
+      select(undef, undef, undef, 0.1);
+      $elapsed += 0.1;
+    }
+    kill("TERM", $pid);
+    waitpid($pid, 0);
+    exit 124;
+  ' "$TIMEOUT_SECONDS" "$@" 2>/dev/null
+}
+
+# --- Detect each provider ---
+
+providers=()
+
+# Anthropic — always available (host runtime)
+providers+=("$(json_provider "anthropic" "true" "subagent" "native" '"opus","sonnet","haiku"')")
+
+# OpenAI via Codex CLI
+codex_bin="$(check_command codex)"
+if [[ -n "$codex_bin" ]] && run_with_timeout codex --version >/dev/null 2>&1; then
+  providers+=("$(json_provider "openai" "true" "codex_exec" "$codex_bin" '"gpt-5.4"')")
+else
+  providers+=("$(json_provider "openai" "false" "codex_exec" "${codex_bin:-not_found}" '')")
+fi
+
+# Google via Gemini CLI
+gemini_bin="$(check_command gemini)"
+if [[ -n "$gemini_bin" ]] && run_with_timeout gemini --version >/dev/null 2>&1; then
+  providers+=("$(json_provider "google" "true" "gemini_cli" "$gemini_bin" '"gemini-3-pro"')")
+else
+  providers+=("$(json_provider "google" "false" "gemini_cli" "${gemini_bin:-not_found}" '')")
+fi
+
+# Ollama (local models)
+ollama_bin="$(check_command ollama)"
+ollama_available=false
+ollama_models=""
+if [[ -n "$ollama_bin" ]]; then
+  # Check if ollama server is running by listing models
+  if model_list="$(run_with_timeout ollama list 2>/dev/null)"; then
+    ollama_available=true
+    # Parse model names from 'ollama list' output (skip header line, take first column)
+    ollama_models="$(echo "$model_list" | tail -n +2 | awk '{print $1}' | head -5 | \
+      sed 's/.*/"&"/' | paste -sd ',' -)"
+  fi
+fi
+providers+=("$(json_provider "ollama" "$ollama_available" "ollama_run" "${ollama_bin:-not_found}" "$ollama_models")")
+
+# Cursor via Cursor CLI (cursor-agent) — model aggregator: serves GPT-5.x,
+# Claude, Gemini, and Grok families through one binary + CURSOR_API_KEY.
+cursor_bin="$(check_command cursor-agent)"
+if [[ -n "$cursor_bin" ]] && run_with_timeout cursor-agent --version >/dev/null 2>&1; then
+  # Cross-family defaults so a Cursor seat adds real diversity, not a
+  # second Anthropic-biased model. Verify live IDs with `cursor-agent --list-models`.
+  providers+=("$(json_provider "cursor_cli" "true" "cursor_cli" "$cursor_bin" '"gpt-5.4-high","claude-opus-4-7-thinking-high","gemini-3-pro","grok-4"')")
+else
+  providers+=("$(json_provider "cursor_cli" "false" "cursor_cli" "${cursor_bin:-not_found}" '')")
+fi
+
+# NVIDIA NIM (OpenAI-compatible hosted endpoint at build.nvidia.com)
+# Detection: NVIDIA_API_KEY env var + optional reachability check.
+nim_available=false
+nim_models=""
+nim_endpoint="https://integrate.api.nvidia.com/v1"
+if [[ -n "${NVIDIA_API_KEY:-}" ]]; then
+  # Verify the key is not a placeholder (real keys start with nvapi-)
+  if [[ "${NVIDIA_API_KEY}" =~ ^nvapi- ]]; then
+    # Optional: confirm catalog reachability. Skip if curl missing or offline.
+    # The auth header is passed via process substitution so the key never
+    # appears in curl's argv (visible to other local users via `ps`).
+    if command -v curl >/dev/null 2>&1; then
+      if run_with_timeout curl -sf -o /dev/null \
+          -H @<(printf 'Authorization: Bearer %s\n' "${NVIDIA_API_KEY}") \
+          "${nim_endpoint}/models" 2>/dev/null; then
+        nim_available=true
+      fi
+    else
+      # Curl unavailable; trust env var presence + key prefix as availability signal.
+      nim_available=true
+    fi
+    # Default model suggestions (verify live IDs at build.nvidia.com/models).
+    nim_models='"deepseek-ai/deepseek-v4-pro","moonshotai/kimi-k2.6","minimaxai/minimax-m2.7","z-ai/glm-5.1","qwen/qwen3.5-397b-a17b"'
+  fi
+fi
+providers+=("$(json_provider "nvidia_nim" "$nim_available" "openai_compatible_api" "$nim_endpoint" "$nim_models")")
+
+# --- Build JSON output ---
+
+available_count=0
+for p in "${providers[@]}"; do
+  if echo "$p" | grep -q '"available":true'; then
+    ((available_count+=1))
+  fi
+done
+
+multi_provider=false
+if [[ "$available_count" -ge 2 ]]; then
+  multi_provider=true
+fi
+
+# Assemble providers array
+provider_json=""
+for i in "${!providers[@]}"; do
+  if [[ $i -gt 0 ]]; then
+    provider_json+=","
+  fi
+  provider_json+="${providers[$i]}"
+done
+
+printf '{"providers":[%s],"provider_count":%d,"multi_provider":%s}\n' \
+  "$provider_json" "$available_count" "$multi_provider"

package/scripts/gen-star-history.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Generate self-hosted GitHub star-history charts (light + dark SVG).
+
+Replaces the api.star-history.com embed, whose backend lowercases repo
+owners and serves an empty chart for this repo. Fetches stargazer
+timestamps via `gh api` (works locally when authenticated and in CI via
+GH_TOKEN) and renders two dependency-free SVGs tuned for GitHub's light
+and dark README surfaces, selected with a <picture> element.
+
+Usage: python3 scripts/gen-star-history.py <owner/repo> <out_prefix>
+Writes <out_prefix>-light.svg and <out_prefix>-dark.svg
+"""
+
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+W, H = 800, 400
+MARGIN = {"l": 56, "r": 24, "t": 52, "b": 40}
+
+THEMES = {
+    "light": {
+        "line": "#2563eb", "area_opacity": 0.10,
+        "ink": "#1f2328", "muted": "#59636e", "grid": "#d1d9e0",
+    },
+    "dark": {
+        "line": "#4493f8", "area_opacity": 0.14,
+        "ink": "#e6edf3", "muted": "#8b949e", "grid": "#30363d",
+    },
+}
+
+MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+          "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+
+
+def fetch_star_dates(repo: str) -> list[datetime]:
+    out = subprocess.run(
+        ["gh", "api", f"repos/{repo}/stargazers", "--paginate",
+         "-H", "Accept: application/vnd.github.star+json",
+         "-q", ".[].starred_at"],
+        capture_output=True, text=True, check=True,
+    ).stdout.split()
+    dates = sorted(datetime.fromisoformat(d.replace("Z", "+00:00")) for d in out)
+    if not dates:
+        raise SystemExit(f"no stargazer data returned for {repo}")
+    return dates
+
+
+def build_series(dates: list[datetime]) -> list[tuple[datetime, int]]:
+    # Cumulative count per day, then evenly sampled to <= 160 points.
+    daily: dict[str, int] = {}
+    for i, d in enumerate(dates, start=1):
+        daily[d.strftime("%Y-%m-%d")] = i
+    pts = [(datetime.fromisoformat(k).replace(tzinfo=timezone.utc), v)
+           for k, v in sorted(daily.items())]
+    if len(pts) > 160:
+        step = (len(pts) - 1) / 159
+        pts = [pts[round(i * step)] for i in range(160)]
+    return pts
+
+
+def nice_step(max_v: int) -> int:
+    for step in (50, 100, 250, 500, 1000, 2000, 5000, 10000):
+        if max_v / step <= 6:
+            return step
+    return 20000
+
+
+def fmt_k(v: int) -> str:
+    if v >= 1000:
+        return f"{v/1000:g}K"
+    return str(v)
+
+
+def render(repo: str, pts: list[tuple[datetime, int]], theme: dict) -> str:
+    x0, x1 = pts[0][0].timestamp(), pts[-1][0].timestamp()
+    y_max_raw = pts[-1][1]
+    step = nice_step(y_max_raw)
+    y_max = ((y_max_raw // step) + 1) * step
+    plot_w = W - MARGIN["l"] - MARGIN["r"]
+    plot_h = H - MARGIN["t"] - MARGIN["b"]
+
+    def sx(ts: float) -> float:
+        return MARGIN["l"] + (ts - x0) / max(x1 - x0, 1) * plot_w
+
+    def sy(v: float) -> float:
+        return MARGIN["t"] + plot_h - v / y_max * plot_h
+
+    line_d = " ".join(
+        f"{'M' if i == 0 else 'L'}{sx(d.timestamp()):.1f},{sy(v):.1f}"
+        for i, (d, v) in enumerate(pts)
+    )
+    base_y = sy(0)
+    area_d = f"{line_d} L{sx(x1):.1f},{base_y:.1f} L{sx(x0):.1f},{base_y:.1f} Z"
+
+    grid, ylabels = [], []
+    for v in range(step, y_max + 1, step):
+        y = sy(v)
+        grid.append(f'<line x1="{MARGIN["l"]}" y1="{y:.1f}" x2="{W - MARGIN["r"]}" y2="{y:.1f}" '
+                    f'stroke="{theme["grid"]}" stroke-width="1"/>')
+        ylabels.append(f'<text x="{MARGIN["l"] - 8}" y="{y + 4:.1f}" text-anchor="end" '
+                       f'fill="{theme["muted"]}" font-size="12">{fmt_k(v)}</text>')
+
+    xlabels = []
+    seen = set()
+    for d, _ in pts:
+        key = (d.year, d.month)
+        if key in seen:
+            continue
+        seen.add(key)
+        ts = datetime(d.year, d.month, 1, tzinfo=timezone.utc).timestamp()
+        if ts < x0:
+            ts = x0
+        label = MONTHS[d.month - 1] + (f" '{str(d.year)[2:]}" if d.month == 1 or len(seen) == 1 else "")
+        xlabels.append(f'<text x="{sx(ts):.1f}" y="{H - MARGIN["b"] + 20}" text-anchor="middle" '
+                       f'fill="{theme["muted"]}" font-size="12">{label}</text>')
+
+    end_x, end_y = sx(x1), sy(y_max_raw)
+    label_anchor = "end"
+    label_x = end_x - 10
+    updated = pts[-1][0].strftime("%b %-d, %Y")
+
+    font = "font-family=\"-apple-system,'Segoe UI',Helvetica,Arial,sans-serif\""
+    return f'''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {W} {H}" width="{W}" height="{H}" role="img" aria-label="Cumulative GitHub stars for {repo}: {y_max_raw:,} as of {updated}">
+  <g {font}>
+    <text x="{MARGIN["l"]}" y="24" fill="{theme["ink"]}" font-size="15" font-weight="600">{repo} — GitHub stars</text>
+    <text x="{W - MARGIN["r"] - 8}" y="24" text-anchor="end" fill="{theme["muted"]}" font-size="11">updated {updated}</text>
+    {''.join(grid)}
+    <line x1="{MARGIN["l"]}" y1="{base_y:.1f}" x2="{W - MARGIN["r"]}" y2="{base_y:.1f}" stroke="{theme["grid"]}" stroke-width="1"/>
+    {''.join(ylabels)}
+    {''.join(xlabels)}
+    <path d="{area_d}" fill="{theme["line"]}" fill-opacity="{theme["area_opacity"]}" stroke="none"/>
+    <path d="{line_d}" fill="none" stroke="{theme["line"]}" stroke-width="2" stroke-linejoin="round" stroke-linecap="round"/>
+    <circle cx="{end_x:.1f}" cy="{end_y:.1f}" r="4" fill="{theme["line"]}"/>
+    <text x="{label_x:.1f}" y="{end_y - 10:.1f}" text-anchor="{label_anchor}" fill="{theme["ink"]}" font-size="13" font-weight="600">{y_max_raw:,} ★</text>
+  </g>
+</svg>
+'''
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        raise SystemExit(__doc__)
+    repo, prefix = sys.argv[1], sys.argv[2]
+    pts = build_series(fetch_star_dates(repo))
+    for mode, theme in THEMES.items():
+        path = f"{prefix}-{mode}.svg"
+        with open(path, "w") as f:
+            f.write(render(repo, pts, theme))
+        print(f"wrote {path} ({pts[-1][1]} stars, {len(pts)} points)")
+
+
+if __name__ == "__main__":
+    main()