Onboarding Guide

Overview

This guide walks new team members through the full onboarding process — from cloning the repository to previewing your first content page. It applies to all three project roles: editors, implementors, and developers.

Who this is for

• Implementors setting up the project for the first time for a client site
• Developers and editors joining the project who need a working local environment

Prerequisites

Before starting, ensure you have:

• Node.js 22+ — The project requires Node 22 or later. Verify with node --version.
• Git — Any recent version. Verify with git --version.
• A code editor — VS Code is recommended but not required.

Familiarity with Astro, Tailwind CSS, and TypeScript is helpful but not required for editors working only with content.

Cloning the repository

git clone <repository-url>
cd astro-agency

Replace <repository-url> with the actual repository URL provided by your team lead.

Initial setup

Install dependencies and verify the development server starts:

npm install
npm run dev

The dev server runs on localhost:4321 by default. Open it in your browser to confirm everything is working.

Project structure overview

The project follows a core/site ownership split that separates the reusable theme framework from per-site customization:

• src/core/ — Theme framework code (CORE-OWNED). Components, token definitions, config schemas, and shared utilities. These files are not modified for individual client sites.
• src/site/ — Per-site customization (SITE-OWNED). Site identity, theme overrides, brand assets, and component overrides. This is where client-specific changes go.
• src/content/ — Content collections (pages, articles, docs, fragments). Content files are authored in Markdown with frontmatter metadata.

Note: For the full directory structure and what each folder contains, see DOC-00035 (Directory Structure).

Key files to read first

These files provide essential project context:

File	Purpose
AGENTS.md	Full project guide — conventions, layout, commands
CLAUDE.md	AI agent-specific context (useful even for human developers)
.docs/charter.md	Project charter with 28 decision sections governing the architecture
ARCHITECTURE.md	Implemented system design, populated as code ships

First site configuration

The main site configuration lives in src/site/config/site.ts. This file defines site identity: name, tagline, default metadata, and other site-wide settings.

Note: For full configuration details, see DOC-00002 (Site Configuration).

First content page

To create your first content page:

1. Create a new Markdown file in src/content/pages/, for example src/content/pages/my-first-page.md.

2. Add the required frontmatter:

   ---
   title: My First Page
   description: A brief description of this page.
   ---
   
   ## Welcome
   
   This is the body content. Start body headings at `##` — the frontmatter
   title renders as the page H1.

3. Save the file and check the dev server. The page should be available at /my-first-page/.

Note: Do not use # headings in the body. The frontmatter title already renders as the page H1. Start body headings at ##.

Running validation

The project provides several validation commands:

Command	When to use
npm run dev	Local development — preview changes in the browser
npx astro check	Type checking — safe to run mid-edit
npm run build	Production build — use at implementation checkpoints
npm run validate	Full quality gate — run before commits and PRs

npm run validate runs the complete pipeline: format check, lint, token lint, content ingestion lint, type checking, build, and accessibility checks. Always run it before committing.

Coding conventions

Key conventions to follow from the start:

• Ownership markers — Every source file has // CORE-OWNED or // SITE-OWNED at the top. Respect the boundary: site work goes in site-owned files.
• Semantic tokens only — Components use --st-* tokens, never raw color values or primitives.
• Zero-JS by default — Hydrate only interactive islands with explicit justification. Vanilla TypeScript is the interactivity layer.
• Use project primitives — Use Heading, Button, Icon, and Link components instead of raw HTML elements.

Note: For the complete set of coding conventions, see DOC-00042 (Development Guidelines).

Getting help

When you need context or direction:

• TODO.md — Current active work and near-term priorities.
• BACKLOG.md — Deferred ideas and parking lot items.
• .docs/decisions.md — Append-only log of implementation decisions with rationale.
• .docs/charter.md — Authoritative source for architectural decisions. Each of the 28 sections covers a specific domain (tokens, components, rendering, etc.).