Directory Structure

This reference documents the project’s file and directory layout. It covers root files, the docs/ directory, the src/ source tree with ownership annotations, and naming conventions. For the ownership model itself (sync behavior, override rules, breaking change policy), see the File Ownership Model (DOC-00006).

Who this is for

• Implementors placing new components, utilities, or config files in the correct location.
• Developers understanding which directories are safe to modify on a per-site basis.
• AI agents determining where to create or edit files without violating ownership boundaries.

Root Files

The repository root contains seven tracked files. Each has a single purpose:

File	Purpose
README.md	Project overview, quick start, tech stack summary
AGENTS.md	Shared operational guide for all AI agents — tech stack, commands, conventions
CLAUDE.md	Claude-specific overlay — tool preferences, working style
ARCHITECTURE.md	Implemented system design — populated as code ships
CHANGELOG.md	Dated record of shipped changes
TODO.md	Active and near-term work items
BACKLOG.md	Deferred ideas and parking lot

AGENTS.md is the single source of truth for “how this project works.” CLAUDE.md references it and adds Claude-specific context. ARCHITECTURE.md stands alone as a system design reference.

.docs/ Directory

.docs/
├── charter.md           # Frozen project charter — all high-level decisions
├── decisions.md         # Append-only implementation decision log
├── notes.md             # Working notes, research, open questions
├── roadmap.md           # Program roadmap — initiative sequencing and status
├── plans/               # Work plans and verification checklists
├── standards/           # Project-wide standards (GIT.md, MANUAL-TESTING.md)
├── reference/           # Reference material (screenshots, prior art)
└── archive/             # Completed plans and superseded documents (flat)

Key conventions:

• charter.md is frozen after approval. Ongoing implementation decisions go in decisions.md.
• plans/ uses the naming pattern YYYY-MM-DD-<topic>.md with verification checklists as YYYY-MM-DD-<topic>-verification.md.
• archive/ is flat. Completed or superseded documents move here rather than being deleted.
• standards/ holds enforced conventions (commit format, verification format) that all contributors must follow.

src/ Directory

The source tree separates core framework code from site-specific customization using two ownership zones. Every file belongs to exactly one owner: CORE or SITE.

src/
├── components/        # Site-specific components (SITE-OWNED)
├── core/              # Core-owned split-concern files (CORE-OWNED)
│   ├── components/    # UI components organized by purpose
│   │   ├── base/      # Document shell, SEO, analytics, skip link
│   │   ├── layouts/   # Page layouts (BaseLayout, PageGridLayout, BlankLayout)
│   │   ├── nav/       # Header, footer, mobile menu
│   │   ├── primitives/# Buttons, headings, icons, links, badges
│   │   ├── sections/  # Hero, CTA, features, testimonials, pricing
│   │   ├── forms/     # Form primitives and section forms
│   │   ├── search/    # Search modal and results
│   │   └── ui/        # Breadcrumbs, pagination, TOC, empty state
│   ├── config/        # Config schemas, requirements catalog
│   ├── styles/        # Token definitions, base CSS
│   └── assets/        # Core assets (icons, vendor files)
├── site/              # Site-owned overrides, config, assets (SITE-OWNED)
│   ├── config/        # Site identity, nav, fonts, analytics config
│   ├── styles/        # Theme overrides
│   ├── assets/        # Site images, icons, fonts
│   └── components/    # Component overrides (shadow core components)
├── content/           # Content collections (SITE-OWNED)
├── lib/               # Utilities, contracts, helpers (CORE-OWNED)
└── pages/             # Route files (SITE-OWNED; pages/api/* is CORE-OWNED)

Ownership Summary

Path	Owner	Notes
src/components/*	SITE-OWNED	Site-specific components (not overrides)
src/core/*	CORE-OWNED	Core components, config, styles, assets
src/lib/*	CORE-OWNED	Shared utilities and contracts
src/content.config.ts	SITE-OWNED	Content collection schemas (imports docs collection from src/core/config/docs-collection.ts)
src/site/*	SITE-OWNED	Site side of split-concern folders
src/content/*	SITE-OWNED	Content collections (pages, articles, docs)
src/pages/*	SITE-OWNED	Route files for page composition
src/pages/api/*	CORE-OWNED	API routes (exception to site-owned pages)

Core-owned files (src/core/, src/lib/, scripts/) require a first-line // CORE-OWNED marker. Site-owned directory paths (src/site/, src/components/, src/content/) determine ownership by location — markers are recommended for clarity but not required. src/pages/ uses marker-based ownership: // CORE-OWNED opts into sync; unmarked files are treated as site-owned. Markdown content files do not need markers. See File Ownership Model (DOC-00006) for the full rules.

File Naming Conventions

File Type	Convention	Example
Astro components	PascalCase	Button.astro, Hero.astro
TypeScript utilities	kebab-case	search-client.ts, nav-helpers.ts
CSS files	kebab-case	base-reset.css, token-primitives.css
Content markdown	kebab-case	directory-structure.md, intro-core.md
Config files	kebab-case	site.ts, requirements.catalog.ts
Work plans	Date-prefixed	2026-03-01-search-integration.md

What Is NOT in This Structure

The project intentionally omits:

• No CONTRIBUTING.md — contribution guidance lives in AGENTS.md
• No templates/ directory — no boilerplate scaffolding files
• No generated-docs/, product-specs/, or design-docs/ directories
• No deeply nested archive hierarchies — .docs/archive/ is flat
• No separate requirements catalog directory — the catalog lives in src/core/config/