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

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