/nightly-docs-update

Keeps etanheyman.com/golems in sync with the actual golems repo state. Runs stats collection, updates hardcoded numbers, detects dead references, and creates a PR.

When to Use

• Nightly: Scheduled run to catch stat drift
• Post-merge: After significant golems PRs (new packages, skill additions, test changes)
• Manual: When someone says "docs are stale" or "numbers look wrong"

Prerequisites

• ~/Gits/golems exists and is a git repo
• ~/Gits/etanheyman.com exists and is a git repo
• gh CLI authenticated
• sqlite3 available (for BrainLayer chunk count)
• BrainLayer DB at ~/.local/share/zikaron/zikaron.db

What It Does

The scripts/default.sh script runs in two phases:

Phase 1: Collect Stats (from golems repo)

Stats are written to a temp JSON for the update phase.

Phase 2: Update etanheyman.com (in portfolio repo)

Automatable Updates (sed replacements)

Dead Reference Detection (warn only)

The script scans for references to packages that no longer exist:

Dead refs are reported but not auto-fixed — they may be historically accurate (journey sections).

Phase 3: PR Creation

If any files changed:

1. Create branch chore/nightly-docs-YYYY-MM-DD
2. Commit with conventional message
3. Create PR with diff summary
4. Output PR URL

If no files changed: report "all stats current" and exit 0.

Checklist of Places to Check

This is the full PRD of content that can drift. The script automates most of these.

Hardcoded Numbers (HIGH priority — auto-fixable)

• Package count (currently 11)
• PR count (currently 261+)
• Skill count (currently 55)
• BrainLayer chunk count (currently 291K+)
• Test count and file count

Structural References (MEDIUM priority — detection only)

• Package table in architecture.md matches actual ls packages/
• Monorepo tree in getting-started.md matches filesystem
• No references to removed packages (autonomous, orchestrator, dashboard, ralph, zikaron)
• Install commands reference correct package names (docsite not dashboard)

Semantic Consistency (LOW priority — manual review)

• Golem count consistent across files (currently 7)
• Feature descriptions match actual CLAUDE.md per package
• External links still resolve (BrainLayer repo, VoiceLayer repo)

Edge Cases

• BrainLayer DB missing: Skip chunk count, warn in output
• Tests take too long: Use --skip-tests flag to skip test counting
• gh not authenticated: Skip PR count, warn in output
• etanheyman.com dirty: Refuse to run, ask user to commit/stash first
• No changes detected: Exit 0 with "all current" message (not an error)

Composability

• Called by: Night Shift (@golems/services), manual invocation
• Calls: /pr-loop for the PR creation step (when run manually with --pr-loop)
• Produces: golems-stats.json consumed by etanheyman.com dashboard

Quick Reference

# Full run (collect + update + PR)
/nightly-docs-update
 
# Skip tests (faster, ~15s vs ~70s)
/nightly-docs-update --skip-tests
 
# Stats collection only (no file updates)
/nightly-docs-update --stats-only
 
# Detect dead refs only
/nightly-docs-update --dead-refs-only