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

```bash
# 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`:

```css
--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
```astro
<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
```astro
<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/`:
```astro
---
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