Skip to content

PAPERS_REPOS_AUDIT.md

Latest commit

 

History

History
336 lines (255 loc) · 9.8 KB

PAPERS_REPOS_AUDIT.md

File metadata and controls

336 lines (255 loc) · 9.8 KB
Raw

Papers Repositories Audit - All Projects

Date: 2025-10-29 Auditor: Claude Code Scope: Zoo, Lux, Hanzo, Zen papers repositories

Executive Summary

Audited 4 papers repositories across Zoo, Lux, Hanzo, and Zen projects for similar GitHub Pages/Jekyll configuration issues. Found and fixed issues in 2 repositories (Zoo and Lux). Hanzo and Zen papers repos only compile PDFs and don't deploy to GitHub Pages, so no issues found.

Repositories Audited

Repository Path Deployment Status Issues Found
Zoo Papers /Users/z/work/zoo/papers GitHub Pages ✅ Fixed Jekyll theme conflicts
Lux Papers /Users/z/work/lux/papers GitHub Pages ✅ Fixed Missing .nojekyll
Hanzo Papers /Users/z/work/hanzo/papers None (PDF only) ✅ OK None
Zen Papers /Users/z/work/zen/papers None (PDF only) ✅ OK None

1. Zoo Papers (/Users/z/work/zoo/papers)

🌐 Deployment

❌ Issues Found

Issue 1: Jekyll Theme Configuration Conflicts

Severity: High Impact: Console errors on live site

Root Cause:

  • _config.yml had Jekyll theme configuration (jekyll-theme-minimal)
  • Theme tried to load external JavaScript files (scale.fix.js)
  • Workflow generates standalone static HTML, not Jekyll site
  • Conflict between workflow's .nojekyll and config file

Console Errors:

Loading failed for the <script> with source
"https://papers.zoo.ngo/papers/assets/js/scale.fix.js"

Issue 2: Cloudflare Beacon Injection

Severity: Medium Impact: Console errors, but not site-breaking

Root Cause:

  • Cloudflare automatically injects analytics/bot protection scripts
  • CORS policy blocks beacon.min.js
  • Subresource Integrity (SRI) hash mismatch

Console Errors:

Cross-Origin Request Blocked: The Same Origin Policy disallows reading
the remote resource at https://static.cloudflareinsights.com/beacon.min.js

✅ Fixes Applied

  1. Disabled Jekyll Theme (Commit: 1204968)

    • Commented out theme: jekyll-theme-minimal
    • Commented out remote_theme: pages-themes/minimal@v0.2.0
    • Commented out all Jekyll plugins
    • Already had .nojekyll in workflow

  2. Created Cloudflare Configuration Guide

    • Added CLOUDFLARE_CONFIG.md with detailed instructions
    • Requires manual Cloudflare dashboard configuration
    • Instructions to disable Browser Insights and Bot Fight Mode

📋 Verification Steps

# Check deployment
gh run list --repo zooai/papers --limit 3

# Visit site
open https://papers.zoo.ngo

Result: ✅ Deployment successful, scale.fix.js error resolved

2. Lux Papers (/Users/z/work/lux/papers)

🌐 Deployment

⚠️ Issues Found

Issue: Missing .nojekyll File

Severity: Low (preventative) Impact: Potential future issues with Jekyll processing

Root Cause:

  • Next.js generates _next/ directory (starts with underscore)
  • GitHub Pages Jekyll processing ignores underscore directories by default
  • No explicit .nojekyll file to prevent Jekyll processing

Potential Issues:

  • Jekyll might try to process the site
  • MIME type issues with static assets
  • Script loading failures
  • Inconsistent behavior across deployments

✅ Fix Applied

Added .nojekyll File (Commit: 3726723)

  • Created public/.nojekyll file
  • Next.js build copies it to out/ directory
  • Explicitly disables Jekyll processing on GitHub Pages

📋 Configuration

Next.js Static Export:

// next.config.js
{
  output: 'export',
  images: { unoptimized: true },
  trailingSlash: true,
  basePath: process.env.NEXT_PUBLIC_BASE_PATH || '',
}

Build Process:

  1. pnpm build → generates static site in out/
  2. out/ contains CNAME file with papers.lux.network
  3. .nojekyll now included in out/
  4. Uploaded to GitHub Pages

📋 Verification Steps

# Check deployment
gh run list --repo luxfi/papers --limit 3

# Verify .nojekyll in build output
ls -la /Users/z/work/lux/papers/out/.nojekyll

# Visit site
open https://papers.lux.network

Result: ✅ Fix deployed, no issues expected

3. Hanzo Papers (/Users/z/work/hanzo/papers)

📦 Build Configuration

  • Method: Docker + LaTeX compilation only
  • Deployment: None (PDFs stored as GitHub artifacts)
  • Workflow: .github/workflows/build-papers.yml

✅ Status: No Issues

Architecture:

  • Compiles LaTeX files to PDFs using texlive/texlive:latest Docker image
  • Uploads PDFs as GitHub Actions artifacts (90-day retention)
  • Creates releases on tags with attached PDFs
  • No GitHub Pages deployment → No Jekyll issues possible

Papers Included:

  • hanzo-aso.tex → ASO (Adaptive Semantic Optimization)
  • hanzo-dso.tex → DSO (Decentralized Semantic Optimization)
  • hanzo-hmm.tex → HMM (Hamiltonian Market Maker)
  • hanzo-network-architecture.tex
  • hanzo-network-whitepaper.tex
  • Plus Jin and Zen subdirectories

📋 Workflow Summary

- Checkout repository
- Set up Docker Buildx
- Build PDFs with LaTeX (via Docker)
- Upload PDFs as artifacts
- Create Release on Tag (optional)

No Action Required: ✅ Repository is correctly configured for its purpose

4. Zen Papers (/Users/z/work/zen/papers)

📦 Build Configuration

  • Method: Docker + LaTeX compilation
  • Deployment: PDFs committed back to repo + GitHub releases
  • Workflow: .github/workflows/compile-papers.yml

✅ Status: No Issues

Architecture:

  • Compiles LaTeX files to PDFs using texlive/texlive:latest container
  • Stores PDFs in pdfs/ directory
  • Commits PDFs back to repository with [skip ci]
  • Creates GitHub releases with PDFs attached
  • No GitHub Pages deployment → No Jekyll issues possible

Papers Included (22 Zen family models):

  • zen-3d.tex → 3D understanding
  • zen-agent.tex → Agent workflows
  • zen-artist*.tex → Multiple artist models
  • zen-coder_whitepaper.tex → Code generation
  • zen-designer*.tex → Multiple designer models
  • zen-director.tex → Video direction
  • zen-eco_whitepaper.tex → Ecosystem overview
  • zen-foley.tex → Audio synthesis
  • zen-guard_whitepaper.tex → Safety model
  • zen-musician.tex → Music generation
  • zen-nano_whitepaper.tex → 0.6B parameter model
  • zen-next_whitepaper.tex → Next generation
  • zen-omni_whitepaper.tex → Multimodal
  • zen-reranker.tex → Search reranking
  • zen-scribe_whitepaper.tex → Writing assistant
  • zen-technical-paper.tex → Technical details
  • zen-video.tex → Video generation
  • zen-voyager.tex → Exploration agent
  • zen-world.tex → World modeling
  • zen_family_overview.tex → Family overview

📋 Workflow Summary

- Checkout repository
- Install LaTeX (texlive-full)
- Compile all .tex files to PDFs
- Move PDFs to pdfs/ directory
- Upload PDFs as artifacts (90-day retention)
- Create GitHub release with PDFs
- Commit PDFs back to repository

No Action Required: ✅ Repository is correctly configured for its purpose

Additional Finding: Jin Papers (/Users/z/work/hanzo/jin/papers)

📦 Configuration

  • Location: Subdirectory within Hanzo papers
  • Method: Local LaTeX compilation
  • Focus: Jin (multimodal AI framework) research papers

Papers Included:

  • Army grant proposals (AAL/TAC format)
  • FAIR paper submissions
  • JEPA (Joint-Embedding Predictive Architecture) papers
  • A2V2 (Audio-to-Video-to-Audio) whitepaper
  • MOE (Mixture of Experts) proposals

✅ Status: No Issues

  • No automated deployment
  • Compiled manually or via parent Hanzo papers workflow
  • PDFs stored locally with figures/

Summary of Actions Taken

Fixes Applied ✅

  1. Zoo Papers:

    • ✅ Disabled Jekyll theme in _config.yml
    • ✅ Disabled Jekyll plugins
    • ✅ Created CLOUDFLARE_CONFIG.md guide
    • ✅ Committed and deployed

  2. Lux Papers:

    • ✅ Added public/.nojekyll file
    • ✅ Committed and deployed

No Action Needed ✅

  1. Hanzo Papers: Correctly configured (PDF compilation only)
  2. Zen Papers: Correctly configured (PDF compilation only)

Recommendations

For All Repositories

  1. Monitor Deployments:

    • Watch GitHub Actions for any new issues
    • Check console logs after each deployment

  2. Cloudflare Configuration (Zoo & Lux):

    • Follow instructions in CLOUDFLARE_CONFIG.md
    • Disable Browser Insights in Cloudflare dashboard
    • Disable Bot Fight Mode
    • Clear cache after changes

  3. Documentation:

    • Keep README.md files updated
    • Document deployment processes
    • Include troubleshooting guides

Future Preventative Measures

  1. Always use .nojekyll for GitHub Pages deployments
  2. Avoid Jekyll themes when using custom static site generators
  3. Test deployments on staging before production
  4. Monitor console for any script loading errors

Testing Checklist

  • Zoo Papers site loads without scale.fix.js errors
  • Lux Papers has .nojekyll file deployed
  • Hanzo Papers compiles PDFs successfully
  • Zen Papers compiles PDFs successfully
  • All commits pushed to respective repositories
  • Cloudflare configuration updated (requires manual action)
  • Verify Cloudflare beacon errors resolved (after config change)

Contact & Support

For issues related to:

  • Code/Config: Check GitHub repository issues
  • Cloudflare: See CLOUDFLARE_CONFIG.md in Zoo papers
  • Deployments: Check GitHub Actions logs

Audit Complete: 2025-10-29 All Critical Issues Resolved: ✅ Manual Actions Required: Cloudflare dashboard configuration for Zoo/Lux papers