This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
gaia-research is the public-facing lab/portal for the Gaia ecosystem. It is:
_config.yml, robots.txt, sitemap.xml) that currently ships the README as the landing page at https://gaia-research.github.io/gaia-research/.src/, content/, docs/, and experiments/ are being populated for the migration described in CONSOLIDATION_PRD.md. There is no package.json, next.config.*, or Next.js runtime present yet; do not assume npm run dev works.scripts/ that fetch benchmark schemas from the sibling gaia-skill-tree repo and validate contributor submissions.Everything runnable today is a one-off tsx script. There is no build, no test suite, and no lint config in-tree.
# Refresh benchmark-result schema (from sibling gaia-skill-tree checkout or raw GitHub)
# and regenerate content/templates/{gsb,benchmark}-submission.json boilerplates.
npx tsx scripts/generate-templates.ts
# Ingest tool docs (skill-fuse, gaia-operator) into content/tools/.
npx tsx scripts/ingest-tool-docs.ts
# Validate a submission JSON. The script auto-detects GSB vs. general benchmark
# from the top-level "benchmark" field ("GSB" / "Gaia Skill Bench" -> GSB schema).
npx tsx scripts/validate-submissions.ts content/templates/gsb-submission.json
npx tsx scripts/validate-submissions.ts content/templates/benchmark-submission.json
generate-templates.ts looks for ../gaia-skill-tree as a sibling working copy first (via git show dev/sprint-d-benchmark-leaderboard:...), then falls back to the raw GitHub URL, then to a hardcoded fallback schema. If you are offline and the sibling repo is missing, the fallback still produces valid output — but the schema may be out of date relative to upstream.
There is a strict repository boundary enforced by convention (see README.md, ARCHITECTURE.md, CONSOLIDATION_PRD.md):
gaia-research ──► marketing-tasks ──► gaia-skill-tree
gaia-research is committed directly into gaia-skill-tree. Changes flow through marketing-tasks first.gaia-skill-tree owns the ground-truth registry.json and the canonical JSON schemas. content/schemas/ in this repo is a derived cache — treat it as regenerable output, not source. If you need to change a schema’s shape, change it upstream in gaia-skill-tree and re-run generate-templates.ts here.CONSOLIDATION_PRD.md) is to move all HTML/UI out of gaia-skill-tree into this repo as a Next.js app, leaving gaia-skill-tree as a headless “Gaia-Lite” toolkit. When adding UI, prefer landing it here rather than in gaia-skill-tree.content/schemas/ — cached JSON Schemas (gsb-submission.schema.json, benchmark-result.schema.json). Regenerated by generate-templates.ts.content/templates/ — sample submissions matching each schema; hand-written in generate-templates.ts and used as validator fixtures.content/reports/, content/tools/ — long-form markdown consumed by the future Next.js site.docs/idea-bank/, docs/plans/ — planning notes; not shipped as pages.experiments/ — playground/testbed concepts; expect these to be prototype-quality and not wired into any build.assets/brand/ — mascot art (Milim avatar) and brand vectors referenced from README.md and the future site’s OG image (_config.yml social.og_image).scripts/validate-submissions.ts is a hand-rolled validator, not a generic JSON Schema library — the schema files in content/schemas/ are documentation for contributors and the upstream registry, but the validator hardcodes the rules it actually enforces. Notable specifics:
performance 0.40 / reliability 0.30 / triggering 0.20 / efficiency 0.10. overallScore, if present, must equal the weighted average within 0.01.containerSha must match ^sha256:[a-f0-9]{64}$ in both schemas.version values "1.0", "1", or "v1" only.If you change the schema JSON files, mirror the change in the validator (or vice versa) — they can silently drift.
PRODUCT.md and DESIGN.md define the mascot voice (Milim — high-energy, playful-rigorous) and the visual system (Milim Pink #ec4899, Rimuru Blue #38bdf8, obsidian dark canvas, Bebas Neue + Syne typography). Copy and UI work in this repo should match that register; the ledger-side (/atlas in the future app) uses a more solemn palette per CONSOLIDATION_PRD.md.
When generating or refining images for this repo, use the project skill/playbook and helper scripts:
.agents/skills/gaia-image-production/SKILL.mddocs/assets/pi-image-gen-playbook.mdscripts/assets/docs/assets/asset-production-workflows.mdcontent/assets/asset-ledger.jsoncontent/assets/export-recipes.jsonHard rule: always use image gen 2 / gpt-image-2; never use nano-banana or nano-banana-2 for Gaia Research production assets. If using omniflash, set model_id: "gpt-image-2". If using pi-image-gen / image_generate, confirm the active default model is image gen 2 before generating; if it cannot be confirmed, ask before proceeding.
Generated experiments and intermediate variants should go in assets/workbench/ first. Promote reviewed outputs to assets/generated/ or assets/brand/, then run the asset ledger sync/check scripts.
The site is served by Jekyll with the jekyll-seo-tag plugin (_config.yml). baseurl is /gaia-research — any absolute paths in future content need to account for that prefix. sitemap.xml and robots.txt are hand-maintained.