Cozy-Den/AGENTS.md

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Quick Reference

Project: Cozy Den - Personal landing page for hiddenden.cafe Owner: Latte (gay furry developer, values self-hosting and privacy) Tech Stack: Astro 4.x, TypeScript, Vanilla CSS, Docker + Nginx Aesthetic: Warm coffee/cappuccino theme, cozy hidden den vibes Deployment: Docker containers pushed to Gitea registry at git.hiddenden.cafe

Core Design Principles

1. Cozy Aesthetic - Warm colors, coffee/cappuccino theme, hidden den vibes
2. Self-Hosted - Everything runs on personal infrastructure (homelab/VPS)
3. Privacy First - No tracking, no external dependencies
4. Lightweight - Static HTML/CSS, minimal JavaScript
5. Docker-Ready - Easy deployment via containers

File Structure

cozy-den/
├── src/
│   ├── layouts/
│   │   └── BaseLayout.astro      # Base layout + global styles
│   └── pages/
│       ├── index.astro            # Main landing page
│       └── 404.astro              # Custom 404 page
├── public/
│   ├── favicon.svg                # Coffee emoji favicon
│   └── robots.txt                 # Search engine directives
├── astro.config.mjs               # Astro config with sitemap
├── package.json                   # Dependencies (Astro 4.x, @astrojs/sitemap)
├── Dockerfile                     # Multi-stage: Node builder + Nginx
├── docker-compose.yml             # Local container orchestration
└── nginx.conf                     # Production web server config

Architecture Notes

This is a simple static site following standard Astro conventions:

• Layouts in src/layouts/ for reusable page templates
• Pages in src/pages/ (routes automatically based on filename)
• All content is on a single page (index.astro) with multiple sections
• Custom 404 page with cozy theming
• No client-side JavaScript - pure static HTML/CSS output
• CSS custom properties centralized in BaseLayout.astro for theming
• Accessibility improvements with ARIA labels and semantic HTML

Commands

# Development
npm install          # Install dependencies
npm run dev          # Start dev server at http://localhost:4321
npm run build        # Build for production (runs astro check + astro build)
npm run preview      # Preview production build

# Docker
docker build -t cozy-den .
docker run -d -p 3000:80 --name cozy-den cozy-den
docker-compose up -d

# Deployment to Gitea registry
docker tag cozy-den git.hiddenden.cafe/mats/cozy-den:latest
docker login git.hiddenden.cafe
docker push git.hiddenden.cafe/mats/cozy-den:latest

Color System

All colors use CSS custom properties in BaseLayout.astro:

--color-bg: #1a1410           /* Dark background (deep coffee) */
--color-bg-light: #2a1f18     /* Lighter background for cards */
--color-text: #f4e9d8          /* Cream text */
--color-text-dim: #c4b5a0      /* Dimmed text */
--color-accent: #d4a574        /* Warm accent (coffee with cream) */
--color-accent-bright: #e8bf8e /* Brighter accent for highlights */
--color-warm: #8b6f47          /* Warm brown for borders/accents */

To change theme: Edit these variables. All components update automatically.

Common Modification Patterns

Adding a Section

<section class="section new-section">
  <div class="container">
    <div class="card fade-in">
      <h2>Section Title</h2>
      <p>Content</p>
    </div>
  </div>
</section>

Adding a Service

<div class="service-item">
  <h3><a href="https://service.hiddenden.cafe">🔧 Service Name</a></h3>
  <p>Description of the service</p>
</div>

Adding a New Page

Create new .astro file in src/pages/:

---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="New Page">
  <div class="container">
    <h1>New Page</h1>
  </div>
</BaseLayout>

Note: Pages route based on filename (e.g., about.astro → /about)

Implementation Guidelines

DO:

• Maintain cozy, warm aesthetic (coffee/cappuccino theme)
• Keep site lightweight - static HTML/CSS only, no JavaScript runtime
• Use CSS custom properties for all colors (defined in src/layouts/BaseLayout.astro)
• Use .fade-in class for animations, .card class for consistent card styling
• Test production builds and Docker builds after changes
• Ensure responsive design works on mobile
• Follow standard Astro structure (layouts in src/layouts/, pages in src/pages/)

DON'T:

• Add tracking or external dependencies (privacy-first approach)
• Add client-side JavaScript unless absolutely necessary
• Break the coffee/warm color theme
• Create sterile or corporate design elements

Astro-Specific Notes

• Frontmatter (code between ---) runs at build time only
• <style> tags are scoped by default; use <style is:global> for global styles (see src/layouts/BaseLayout.astro)
• Site generates static HTML at build time - no JavaScript runtime
• Sitemap integration configured in astro.config.mjs via @astrojs/sitemap
• Custom 404 page at src/pages/404.astro with warm, themed styling

Context & Preferences

• Owner: Latte (gay furry developer who values self-hosting, privacy, and open-source)
• Deployment: All deployments via Docker to personal Gitea registry (git.hiddenden.cafe)
• Design Philosophy: Warm, personal, cozy aesthetic over corporate/sterile design
• Technical Background: Owner typically uses Python/Flask, learning Astro with this project

Troubleshooting

Build fails: Check TypeScript config, ensure Node 18+, run astro check Styles not applying: Verify CSS variables are in BaseLayout.astro, check if you need is:global Docker build fails: Ensure package.json and package-lock.json exist Changes not showing: Hard refresh browser, restart dev server, or clear .astro cache

Related Documentation

• PROJECT_CONTEXT.md - Design principles and project philosophy
• DEVELOPMENT.md - Detailed developer documentation
• TODO.md - Current tasks and future feature ideas
• README.md - User-facing setup and deployment guide