Documentation

Welcome to the Ethotechnics documentation. This hub is for contributors across content, design, and engineering. This site is built with Astro and deployed to Cloudflare Workers.

Start by intent

Quick access

Pick the path that matches your immediate goal so you can move without scanning the full index first.

Ship a change safely → Contributing + testing workflow
Edit content quickly → Content workflow + templates
Understand the system → Architecture + build notes

Start here

Get oriented in one pass.

The README and architecture overview provide the fastest path to understanding the build, content workflow, and deployment shape.

Start with the README Review architecture

Quick Start

New to the project? Begin with:

Read the root README for prerequisites and setup
Review ARCHITECTURE to understand the system
Check CONTRIBUTING for development workflow
Read Agents if you’re an AI agent working on this codebase

Common tasks:

Editing content: Content Workflow
Styling changes: Styles (see CSS tokens in app/src/styles/tokens.css)
Build issues: Build Optimizations
Running tests: Testing & Verification

Core Documentation

Architecture & System Design

ARCHITECTURE — High-level system overview with diagrams showing build process and Worker request flow
Build Optimizations — Build system configuration, performance optimizations, and troubleshooting

Development Guides

CONTRIBUTING — General contribution workflow, PR guidelines, and code review process
Content Workflow — Step-by-step guide for content editing, template usage, and site copy management
Agents — Comprehensive guidelines for AI agents (code style, required commands, common pitfalls)

Specialized Guides

MAINTENANCE — Maintenance playbook and runbooks for deployments and troubleshooting
SITEMAP — Sitemap generation and URL structure
Sitemap growth — Route expansion workflow and release note logging
Content templates — Template catalog for new content routes
Research artifact template — Research artifact structure and metadata
Case note template — Case note structure and metadata
Governance explainer template — Governance explainer structure and metadata
Release notes — User-facing changes and sitemap deltas

Directory-Specific Documentation

Each major directory has its own README with specific guidance:

app/src/content/pages/ — Content collection entries, structure, and build flow
app/src/components/ — Shared Astro components and layout primitives
scripts/ — Build scripts and utilities organization
styles/ — CSS architecture, design tokens, and component patterns in app/src/styles/
tests/ — Testing strategy, test types, and when to run what
worker/ — Cloudflare Worker architecture and request handlers

Reference Documentation

Styles Architecture — Visual CSS architecture diagram and layer explanations in app/src/styles/

Need help?

Search these docs first — Use the links above to find relevant guides
Check similar code examples — Look for similar patterns in /app/src/components/ and /styles/components/
Run project checks — bun run verify to check build/lint/test status
Investigate test failures — bun test and bun run test:e2e for specific issues

Pick a starting path

Choose the track that matches what you need right now.