VLA Foundations

Vision-Language-Action Foundations: A living textbook and course repository.

Live Site: https://www.vlm-robotics.dev GitHub: https://github.com/arpg/vla-foundations

Project Overview

This repository serves as the source of truth for:

The Living Textbook: An 8-chapter technical reference on VLAs for Robotics
CSCI 7000 Course Portal: Course logistics, assignments, and student contributions

Tech Stack: Next.js 16, TypeScript, Tailwind CSS, MDX, Contentlayer

Repository Structure

This repository is organized into three main categories: Web Content (rendered as pages), Source Code (executable assignments), and Build Infrastructure (deployment and tooling).

vla-foundations/
├── app/                           # Next.js App Router (web framework)
│   ├── page.tsx                   # Landing page
│   ├── textbook/[slug]/           # Dynamic chapter pages
│   ├── course/                    # Course overview page
│   │   └── assignments/[slug]/    # Dynamic assignment pages
│   ├── contributors/[slug]/       # Dynamic contributor profile pages
│   └── reference/                 # Reference implementations page
│
├── content/                       # All MDX content (rendered as web pages)
│   ├── textbook/                  # 8-chapter VLA textbook (MDX files)
│   │   ├── foundations/           # Chapter 0: Core concepts
│   │   ├── architectures/         # Chapter 1: Model designs
│   │   ├── data/                  # Chapter 2: Dataset construction
│   │   ├── training/              # Chapter 3: Optimization methods
│   │   ├── evaluation/            # Chapter 4: Metrics and benchmarks
│   │   ├── deployment/            # Chapter 5: Production systems
│   │   ├── applications/          # Chapter 6: Real-world use cases
│   │   └── future/                # Chapter 7: Open problems
│   │
│   ├── course/                    # Course materials (MDX files)
│   │   ├── Syllabus.mdx           # Course syllabus
│   │   ├── assignments/           # Assignment specifications (instructor-written)
│   │   │   ├── scratch-0.mdx      # Environment setup assignment
│   │   │   ├── scratch-1.mdx      # Transformer backbone assignment
│   │   │   ├── paper-audit.mdx    # Paper analysis assignment
│   │   │   └── capstone.mdx       # Final project specification
│   │   └── submissions/           # Student submission reports (student-written)
│   │       └── scratch-1/         # Example: student reports for Scratch-1
│   │           └── [student].mdx  # Individual student writeups
│   │
│   └── contributors/              # Contributor profiles (student-written)
│       └── [github-handle].mdx    # One profile per contributor
│
├── src/                           # Executable source code (NOT rendered as web pages)
│   └── assignments/               # Assignment code templates and solutions
│       └── scratch-1/             # Example: Transformer implementation
│           ├── README.md          # Minimal README (points to assignment page)
│           ├── backbone.py        # Implementation template with TODOs
│           ├── generate_data.py   # Dataset generator script
│           └── data/              # Generated training data
│
├── components/                    # React UI components
│   └── textbook/                  # Textbook-specific components
│       ├── Sidebar.tsx            # Navigation sidebar
│       └── TextbookLayout.tsx     # Layout wrapper
│
├── lib/                           # Utility libraries
│   └── chapters.ts                # Chapter metadata and utilities
│
├── scripts/                       # Deployment and automation
│   └── deploy.sh                  # Production deployment script
│
├── .github/                       # GitHub configuration
│   └── workflows/
│       └── vla-audit.yml          # CI/CD: PR validation, build checks
│
├── next.config.ts                 # Next.js configuration
├── tailwind.config.ts             # Tailwind CSS configuration
├── package.json                   # Node.js dependencies
└── README.md                      # This file

Directory Purpose Guidelines

content/ - Source of truth for all web content

Written in MDX (Markdown + JSX)
Rendered as web pages on vlm-robotics.dev
Instructor writes: textbook chapters, assignment specs, syllabus
Students write: contributor profiles, submission reports

src/ - Executable code (Python, etc.)

Assignment implementation templates
Utility scripts and data generators
NOT rendered as web pages
READMEs are minimal and point to assignment pages (single source of truth)

app/ - Next.js routing and page components

Defines URL structure and page layouts
Connects routes to content in content/
Modified when adding new page types or routes

Important: README Policy for `src/assignments/`

All READMEs in src/assignments/ are intentionally minimal. They contain only:

Link to the canonical assignment page on vlm-robotics.dev
Quick start commands
File list

Full assignment details (requirements, debugging tips, resources, submission checklists) are maintained exclusively in content/course/assignments/*.mdx. This ensures a single source of truth and prevents documentation drift.

The 8-Chapter Textbook

Foundations - Core concepts and problem formulation
Architectures - Model designs and network topologies
Data - Dataset construction and curation strategies
Training - Optimization and fine-tuning methods
Evaluation - Metrics and benchmarking protocols
Deployment - Production systems and scaling
Applications - Real-world use cases and case studies
Future Directions - Open problems and research frontiers

Development Workflow

Initial Setup

# Clone the repository
git clone https://github.com/arpg/vla-foundations.git
cd vla-foundations

# Install dependencies
pnpm install

# Run development server
pnpm dev

Navigate to http://localhost:3000 to see the site.

Adding Content

New Textbook Section

# Create a new MDX file in the appropriate chapter
touch content/textbook/[chapter-name]/new-section.mdx

---
title: "Section Title"
chapter: 1
subsection: 5
---

# Your Content Here

Include LaTeX: $f(x) = x^2$

\`\`\`python
# Include code examples
def example():
    pass
\`\`\`

New Assignment

touch content/course/assignments/assignment-name.mdx

Building and Deploying

Local Build

# Build the static site
pnpm build

# Preview the production build
pnpm start

Deploy to Production

# Automated deployment to vlm-robotics.dev
./scripts/deploy.sh

This will:

Build the Next.js site locally
Sync to the remote server via rsync
Deploy to https://www.vlm-robotics.dev

Requirements: SSH access with the automation key (~/.ssh/id_ed25519_automation)

Course Workflow

For Students

IMPORTANT: All students must follow this workflow for assignment submissions.

Create your own branch:
```
git checkout -b assignment-name-yourname
```
Example: git checkout -b scratch-1-johndoe
Make your changes:
- Add your code to src/assignments/
- Create your submission report in content/course/submissions/
- Update your contributor profile if needed

Commit your work:

git add .
git commit -m "Complete Assignment X: Your Name"
git push origin assignment-name-yourname

Open a Pull Request:
- Go to https://github.com/arpg/vla-foundations
- Click "Pull requests" → "New pull request"
- Base branch: staging (NOT main)
- Compare branch: your branch name
- Title: Assignment X: Your Name
- Add a description of your work
Wait for CI checks to pass (GitHub Actions will validate your submission)
Wait for instructor review:
- ONLY the instructor can merge pull requests
- The instructor will review your code and report
- You may be asked to make changes
- Once approved, the instructor will merge to staging, then to main

You do NOT have permission to merge your own PRs. All merges are done by the instructor.

For the Instructor

Review student PRs on the staging branch
Provide feedback and request changes if needed
Merge to staging when approved
Periodically merge staging to main
Deploy to production using ./scripts/deploy.sh

CI/CD Automation

GitHub Actions Workflow

The vla-audit.yml workflow runs on all PRs to staging and main:

✅ Contentlayer build validation
✅ MDX syntax checking
✅ LaTeX rendering verification
✅ Full site build

Location: .github/workflows/vla-audit.yml

Branch Protection

main: Requires passing CI checks and instructor approval
staging: Student PR target, requires passing CI

Branching Strategy

main: Production branch (deployed to live site)
staging: Student PR target (integration testing)
Feature branches: feature/assignment-name, paper-audit-N-yourname

Technologies

Core

Next.js 16: Static site generation
TypeScript: Type safety
Tailwind CSS: Styling
MDX: Markdown with JSX

Content Processing

Contentlayer: Content validation
gray-matter: Frontmatter parsing
remark-math + rehype-katex: LaTeX rendering
remark-gfm: GitHub-flavored Markdown

Deployment

Apache: Web server on DigitalOcean
rsync: File synchronization
SSH: Secure remote access

Development Tools

Local Commands

# Development
pnpm dev              # Start dev server (hot reload)
pnpm build            # Build production site
pnpm build-content    # Validate content only
pnpm lint             # Run ESLint

# Deployment
./scripts/deploy.sh   # Deploy to production

Remote Server Access

# SSH into production server
ssh -i ~/.ssh/id_ed25519_automation crh@ristoffer.ch

# Navigate to project
cd /var/www/vlm-robotics.dev

# Manual deployment (if needed)
npm run build
cp -r out/* public_html/

Contributing

Content Guidelines

Technical accuracy: Ensure all claims are well-supported
Clear writing: Avoid jargon unless necessary
LaTeX formatting: Use $inline$ and $$display$$ syntax
Code examples: Include runnable code snippets
References: Cite papers using numbered references

Code Guidelines

TypeScript: Use types for all functions
ESLint: Follow the configured linting rules
Components: Keep components small and focused
Naming: Use descriptive variable and function names

Pull Request Process

Create a descriptive branch name
Write clear commit messages
Ensure all CI checks pass
Request review from instructor
Address feedback and update PR
Merge when approved

Resources

Documentation

Papers & Datasets

Instructor TODO List

Course Content Completion Tasks:

Scratch-0 Assignment: Create full assignment specification in content/course/assignments/scratch-0.mdx
Scratch-1 Assignment: Create full assignment specification in content/course/assignments/scratch-1.mdx
Paper Audit Assignment: Create full assignment specification in content/course/assignments/paper-audit.mdx
Capstone Assignment: Create full assignment specification in content/course/assignments/capstone.mdx
Update /course page: Link assignments once content is ready (remove "Coming soon" placeholders)
Syllabus: Upload current syllabus to Canvas and verify link works
Textbook Chapters: Begin writing content for 8 chapters
Example Paper Audit: Create sample audit for students to reference
Setup Branch Protection: Configure GitHub branch protection rules (students require PRs, instructor can bypass)

Deployment:

Test assignment submission workflow end-to-end
Verify CI/CD pipeline catches common errors
Create assignment grading rubric

Notes:

Syllabus is currently linked to Canvas: https://canvas.colorado.edu/courses/134529/files/82424359/download?download_frd=1
Students must submit 1 paper audit (not 4)
Capstone tracks: Research or Engineering (no survey track)

Contact

Instructor: Christoffer Heckman
Email: christoffer.heckman@colorado.edu
Course: CSCI 7000, Spring 2026
GitHub: https://github.com/arpg/vla-foundations

License

Course materials are for educational use by enrolled students only.

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github/workflows		.github/workflows
app		app
components/textbook		components/textbook
content		content
lib		lib
public		public
scripts		scripts
src/assignments/scratch-1		src/assignments/scratch-1
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
mdx-components.tsx		mdx-components.tsx
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

arpg/vla-foundations

Folders and files

Latest commit

History

Repository files navigation

VLA Foundations

Project Overview

Repository Structure

Directory Purpose Guidelines

Important: README Policy for src/assignments/

The 8-Chapter Textbook

Development Workflow

Initial Setup

Adding Content

New Textbook Section

New Assignment

Building and Deploying

Local Build

Deploy to Production

Course Workflow

For Students

For the Instructor

CI/CD Automation

GitHub Actions Workflow

Branch Protection

Branching Strategy

Technologies

Core

Content Processing

Deployment

Development Tools

Local Commands

Remote Server Access

Contributing

Content Guidelines

Code Guidelines

Pull Request Process

Resources

Documentation

Papers & Datasets

Instructor TODO List

Contact

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

Important: README Policy for `src/assignments/`

Packages