Neural Field Guide

Neural Field Guide is a self-contained personal learning and research program for building intelligent systems from understandable primitives, then using those systems for controlled original experiments.

Built with Codex and GPT-5.6

OpenAI Codex with GPT-5.6 was used across essentially the entire project: curriculum research and architecture, lesson writing, UI and interaction design, implementation, testing, debugging, documentation, and release verification. The project owner set the direction, reviewed the work, and made the final decisions.

The program currently contains 182 lessons across five complete courses:

The course selector sits beside the site identity and changes the complete curriculum context. A canonical lesson URL is /<course-id>/<lesson-id>/; the root resumes the last selected course, and legacy flat LLM lesson URLs forward to their /llm/ locations. The recommended sequence and the places where concepts branch or rejoin are documented in docs/CURRICULUM_ARCHITECTURE.md.

Run locally

Prerequisite: Node.js >=22.13.0. Full release verification also requires Python 3.12; its course dependencies are installed into a fresh temporary environment rather than your global Python installation.

npm install
npm run dev

Open http://localhost:3000/. Progress and project notes stay in browser storage and are isolated by course. Existing LLM progress using the original storage key is migrated on first use. Required lessons, practice, feedback, assessments, and reference artifacts work without an account, API, teacher, or external grader.

Verify the program

npm run hooks:install
npm run ci:verify

npm install installs the reviewed .githooks/ path automatically; npm run hooks:install repairs or confirms it explicitly. The pre-push hook runs the same ci:verify command as GitHub Actions. The verifier installs the exact npm graph, creates an isolated Python 3.12 environment from requirements-ci.txt, runs lint and the complete regression suite, and checks root-hosted plus /neural-field-guide Pages exports. A failed check blocks a normal direct push to main; git push --no-verify is an explicit emergency bypass, not the normal publishing path, and GitHub still refuses deployment when remote verification fails.

npm test remains the focused repository suite when dependencies are already installed. It creates and verifies the root static export, checks preserved learning and experiment artifacts, confirms the current independent page-grade evidence, and runs the complete curriculum, accessibility, and UX regression suite. Documentation-specific invariants can be checked quickly with:

node --test tests/documentation.test.mjs

The current grading rubric, generated 187-page report, objective review, interaction audit, and documentation ownership map are indexed in docs/README.md.

Evidence and optional external experiments

Browser labs and preserved fixtures make mechanisms inspectable, but they are not presented as model-quality measurements. Course-scale validation artifacts retain their provenance and claim boundaries. Heavyweight or accelerator-backed experiments are optional extensions, with smoke checks, full commands, expected invariants, variable observations, stop criteria, and failure-preserving output contracts.

The external execution families cover:

• pinned GPT-2/Qwen tokenizer inspection;
• pinned GPT-2 hidden-state measurement;
• pinned OLMo batch token accounting;
• a matched causal-versus-FIM language-model ablation;
• a matched tiny-diffusion schedule ablation;
• a paired DQN target-network experiment;
• an embodied action-chunk feedback experiment.

Start with external-executions/README.md. The Generative, RL, and Embodied runbooks use the same CLI on Google Colab, another compatible GPU service, or a local environment. No external run is required to complete a course, and no plausible result is treated as measured evidence until its preserved artifact is reviewed.

GitHub Pages deployment target

GitHub Pages is the supported target. npm run build:pages uses Next.js native static export and writes the publishable site to out/; the application has no database, authentication, secret-backed API, or server runtime requirement.

Publication is not active by default. Read docs/GITHUB_PAGES.md before making the repository public or copying the inert workflow template into .github/workflows/.

Repository map

• AGENTS.md: contributor contract and complete lesson teaching standard
• app/course-data.ts and app/course-catalog.ts: LLM source of truth and the five registered course definitions
• app/world-models/, app/generative/, app/rl/, app/embodied/: course-specific curricula, labs, assessments, evidence, and projects
• app/research-courses/: shared implementation contracts for the three research courses
• app/curriculum-graph.ts and app/research-curriculum-manifests.ts: cross-course ownership and released-course manifests
• public/validation-artifacts/ and public/capstone-artifacts/: downloadable, machine-readable reference evidence
• public/experiment-runbooks/: learner-facing copies of optional accelerator experiment instructions
• external-executions/: optional reproduction runners, dependency pins, runbooks, and evidence schemas
• scripts/: deterministic generators and repository verifiers
• docs/: maintained architecture, review, grading, interaction, and publication documentation
• tests/: executable curriculum, content, artifact, accessibility, rendering, and deployment contracts

See docs/README.md before adding a new report. It identifies the canonical maintained documents, generated files, owners, regeneration commands, and retirement policy.