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"
importance: 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/session-log.md with a **Pages:** field listing the page slugs that were edited.
2. At build time, build-data.mjs parses the session log and attaches a changeHistory array to each page in database.json.
3. The data flows to two places:
   • Per-page: A "Change History" section in the PageStatus card shows which sessions touched this page.
   • Site-wide: The Page Changes dashboard shows all page edits across all sessions in a sortable table.

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

Knowledge Base System

SQLite-based system for managing content, sources, and AI summaries.

Setup

Requires .env file:

ANTHROPIC_API_KEY=sk-ant-...

Commands

npm run crux -- analyze scan                   # Scan MDX files, extract sources
npm run crux -- generate summaries             # Generate AI summaries
node scripts/scan-content.mjs --stats          # Show database statistics

Detailed Usage

# Scan content (run after editing MDX files)
node scripts/scan-content.mjs
node scripts/scan-content.mjs --force    # Rescan all files
node scripts/scan-content.mjs --verbose  # Show per-file progress

# Generate summaries via crux
npm run crux -- generate summaries --batch 50
npm run crux -- generate summaries --model sonnet
npm run crux -- generate summaries --id deceptive-alignment
npm run crux -- generate summaries --dry-run

Database Location

All cached data is in .cache/ (gitignored):

• .cache/knowledge.db - SQLite database
• .cache/sources/ - Fetched source documents

Cost Estimates

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