Automation Tools

This page documents all automation tools available for maintaining and improving the knowledge base.

Quick Reference

Page Improvement Workflow

The recommended way to improve wiki pages to quality 5.

Commands

# List pages that need improvement (sorted by priority)
node scripts/page-improver.mjs --list

# Get improvement prompt for a specific page
node scripts/page-improver.mjs economic-disruption

# Show page info only (no prompt)
node scripts/page-improver.mjs racing-dynamics --info

# Filter by quality and importance
node scripts/page-improver.mjs --list --max-qual 3 --min-imp 50

What Makes a Q5 Page

Cost Estimates

Reference Examples

• Gold standard: src/content/docs/knowledge-base/risks/bioweapons.mdx
• Good example: src/content/docs/knowledge-base/risks/racing-dynamics.mdx

Scheduled Updates

The update schedule system tracks which pages are overdue for refresh based on update_frequency (days) in frontmatter. It prioritizes pages by combining staleness with importance.

How Scheduling Works

Each page declares how often it should be updated:

update_frequency: 7     # Check weekly
lastEdited: "2026-01-15"
readerImportance: 85

Priority scoring: staleness x (importance / 100), where staleness = days since edit / update frequency. Pages with staleness >= 1.0 are overdue.

Opting Out: Non-Evergreen Pages

Some pages are point-in-time content (reports, experiments, proposals) that don't need ongoing updates. Set evergreen: false in frontmatter to exclude them from the update schedule:

evergreen: false    # This page is a snapshot, not maintained

Pages with evergreen: false are skipped by the update schedule, the bootstrap script, and the reassign script. All existing report pages under internal/reports/ use this flag.

Commands

# See what needs updating
pnpm crux updates list                        # Top 10 by priority
pnpm crux updates list --overdue --limit=20   # All overdue pages

# Preview triage recommendations (cheap, ~$0.08/page)
pnpm crux updates triage --count=10

# Run updates (triage is ON by default)
pnpm crux updates run --count=5               # Triage + update top 5
pnpm crux updates run --count=3 --no-triage --tier=polish  # Skip triage

# Statistics
pnpm crux updates stats

Cost-Aware Triage

By default, updates run checks for new developments before committing to an expensive update. For each page it does a cheap news check (≈$0.08) using web search + SCRY, then recommends a tier:

Example savings: 10 pages at standard ≈ $65. With triage, if 6 have no news: ≈$26 + $0.80 triage ≈ $27.

Use --no-triage to skip the news check and apply a fixed tier to all pages.

Update Tiers (Page Improver)

# Single page with specific tier
node crux/authoring/page-improver.ts -- <page-id> --tier polish --apply
node crux/authoring/page-improver.ts -- <page-id> --tier standard --apply --grade
node crux/authoring/page-improver.ts -- <page-id> --tier deep --apply --grade

# Auto-select tier via triage
node crux/authoring/page-improver.ts -- <page-id> --tier triage --apply --grade

# Triage only (no update)
node crux/authoring/page-improver.ts -- <page-id> --triage

Page Change Tracking

Claude Code sessions log which wiki pages they modify. This creates a per-page change history that feeds two dashboards.

How It Works

1. Each Claude Code session appends an entry to .claude/sessions/ with a **Pages:** field listing the page slugs that were edited.
2. At build time, build-data.mjs parses session logs and attaches a changeHistory array to each page in database.json.
3. PR numbers are auto-populated at build time via the GitHub API (github-pr-lookup.mjs), mapping branch names to PR numbers. Session logs can also include an explicit **PR:** #123 as an override.
4. The data flows to two places:
   • Per-page: A "Change History" section in the PageStatus card shows which sessions touched this page, with clickable PR links.
   • Site-wide: The Page Changes dashboard shows all page edits across all sessions in a sortable table with PR links.

Session Log Format

The **Pages:** field uses page slugs (filenames without .mdx), comma-separated:

**Pages:** ai-risks, compute-governance, anthropic

Omit the field entirely for infrastructure-only sessions that don't edit wiki pages.

Content Grading

Uses Claude Sonnet API to automatically grade pages with importance, quality, and AI-generated summaries.

Commands

# Preview what would be graded (no API calls)
node scripts/grade-content.mjs --dry-run

# Grade a specific page
node scripts/grade-content.mjs --page scheming

# Grade pages and apply to frontmatter
node scripts/grade-content.mjs --limit 10 --apply

# Grade a category with parallel processing
node scripts/grade-content.mjs --category responses --parallel 3

# Skip already-graded pages
node scripts/grade-content.mjs --skip-graded --limit 50

Options

Grading Criteria

Importance (0-100):

• 90-100: Essential for prioritization (core interventions, key risk mechanisms)
• 70-89: High value (concrete responses, major risk categories)
• 50-69: Useful context (supporting analysis, secondary risks)
• 30-49: Reference material (historical, profiles, niche)
• 0-29: Peripheral (internal docs, stubs)

Quality (0-100):

• 80-100: Comprehensive (2+ tables, 1+ diagram, 5+ citations, quantified claims)
• 60-79: Good (1+ table, 3+ citations, mostly prose)
• 40-59: Adequate (structure but lacks tables/citations)
• 20-39: Draft (poorly structured, heavy bullets, no evidence)
• 0-19: Stub (minimal content)

Cost Estimate

≈$0.02 per page, ≈$6 for all 329 pages

Validation Suite

All validators are accessible via the unified crux CLI:

npm run validate              # Run all validators
npm run crux -- validate --help   # List all validators

Individual Validators

Advanced Usage

# Run specific validators
npm run crux -- validate compile --quick
npm run crux -- validate unified --rules=dollar-signs,markdown-lists

# Skip specific checks
npm run crux -- validate all --skip=component-refs

# CI mode
npm run validate:ci

Citation & Content Tools

Tools for verifying citations, fetching source content, and scanning wiki pages. Data is stored in the wiki-server PostgreSQL database and accessed via Hono RPC API.

Citation Verification

# Verify all citations on a page (fetches URLs, checks quotes)
pnpm crux citations verify <page-id>

# Run citation audits across multiple pages
pnpm crux citations audit

# View citation archive for a page
pnpm crux citations show <page-id>

Citation results are stored in two places:

• YAML archive (data/citation-archive/<page-id>.yaml) — per-page verification records, checked into git
• PostgreSQL (citation_content table) — full fetched text for quote verification, accessed via wiki-server API

Content Scanning

# Scan MDX files for content analysis
pnpm crux scan-content

Source Fetching

When verifying citations, the system fetches source URLs through a multi-layer cache:

1. In-memory LRU cache (500 entries, session-scoped)
2. PostgreSQL citation_content (durable, cross-machine)
3. Network fetch via Firecrawl API or built-in fallback

Fetched content is cached in .cache/sources/ locally and persisted to PostgreSQL for future sessions.

Environment Variables

Data Layer

Build Data

Important: Data build must run before site build.

npm run build:data    # Regenerate all data files
npm run dev           # Auto-runs build:data first
npm run build         # Auto-runs build:data first

Generated Files

After running build:data:

• src/data/database.json - Main entity database
• src/data/entities.json - Entity definitions
• src/data/backlinks.json - Cross-references
• src/data/tagIndex.json - Tag index
• src/data/pathRegistry.json - URL path mappings
• src/data/pages.json - Page metadata for scripts

Other Data Scripts

npm run sync:descriptions    # Sync model descriptions from files
npm run extract              # Extract data from pages
npm run generate-yaml        # Generate YAML from data
npm run cleanup-data         # Clean up data files

Content Management CLI

Unified tool for managing and improving content quality via crux content.

Commands

# Improve pages
npm run crux -- content improve <page-id>

# Grade pages using Claude API
npm run crux -- content grade --page scheming
npm run crux -- content grade --limit 5 --apply

# Regrade pages
npm run crux -- content regrade --page scheming

# Create new pages
npm run crux -- content create --type risk --file input.yaml

Options

Resource Linking

Convert URLs to R Components

# Find URLs that can be converted to <R> components
node scripts/map-urls-to-resources.mjs expertise-atrophy  # Specific file
node scripts/map-urls-to-resources.mjs                     # All files
node scripts/map-urls-to-resources.mjs --stats             # Statistics only

# Auto-convert markdown links to R components
node scripts/convert-links-to-r.mjs --dry-run              # Preview
node scripts/convert-links-to-r.mjs --apply                # Apply changes

Export Resources

node scripts/utils/export-resources.mjs        # Export resource data

Content Generation

Generate New Pages

# Generate a model page from YAML input
npm run crux -- generate content --type model --file input.yaml

# Generate a risk page
npm run crux -- generate content --type risk --file input.yaml

# Generate a response page
npm run crux -- generate content --type response --file input.yaml

Batch Summaries

npm run crux -- generate summaries --batch 50  # Generate summaries for multiple pages

Testing

npm run test            # Run all tests
npm run test:lib        # Test library functions
npm run test:validators # Test validator functions

Linting and Formatting

npm run lint           # Check for linting issues
npm run lint:fix       # Fix linting issues
npm run format         # Format all files
npm run format:check   # Check formatting without changing

Temporary Files

Convention: All temporary/intermediate files go in .claude/temp/ (gitignored).

Scripts that generate intermediate output (like grading results) write here by default. This keeps the project root clean and prevents accidental commits.

Common Workflows

Improve a Low-Quality Important Page

1. Find candidates:

   node scripts/page-improver.mjs --list --max-qual 3
   

2. Get improvement prompt:

   node scripts/page-improver.mjs economic-disruption
   

3. Run in Claude Code with the generated prompt

4. Validate the result:

   npm run crux -- validate compile
   npm run crux -- validate templates
   

Grade All New Pages

1. Preview:

   node scripts/grade-content.mjs --skip-graded --dry-run
   

2. Grade and apply:

   node scripts/grade-content.mjs --skip-graded --apply --parallel 3
   

3. Review results:

   cat .claude/temp/grades-output.json
   

Check Content Quality Before PR

npm run validate

Update After Editing entities.yaml

npm run build:data
npm run crux -- validate data